API Umbrella: an API gateway where the gateway is the least interesting language in the stack

The pitch is a layer above your code, not a library inside it

The README is short, and its argument is entirely about where the gateway sits. APIs get access control, rate limiting and analytics without implementing them, because the gateway handles those before a request reaches the API. APIs are added rather than modified, since API Umbrella acts as a layer above your APIs so your code does not need changes to benefit. And separate APIs, on different servers or in different languages, can be presented as one cohesive offering at a single endpoint.

For consumers, the standardisation argument is equally concrete. Every API is reachable with the same API key credentials, and every API is documented in one place in a similar fashion. Those two claims are the ones that change how a partner integrates, as opposed to the ones that change how you deploy.

The framing also tells you what this is not. It is not a library, not a code generator, and not something you embed in an application. It is a platform that sits in front, which is why the repository is mostly infrastructure.

Read the Dockerfile to see what you are actually installing

The repository's language is Ruby and its file extensions are mostly Ruby, but the build is where the real architecture shows. The `Dockerfile` stages, in order: a Debian bookworm base, system build dependencies, a `./configure` bootstrap, then `make deps:perp`, `make deps:openresty`, `make deps:trafficserver`, `make deps:fluent-bit`, `make deps:luarocks` and `make deps:envoy`, each followed by `make clean:dev`.

COPY tasks/deps/openresty /app/tasks/deps/
RUN make deps:openresty && make clean:dev

So the request path is OpenResty, meaning nginx with LuaJIT, backed by the Apache Traffic Server cache, with Envoy added as a sidecar and fluent-bit handling log shipping. The gateway topics on the repository confirm the intent: nginx, openresty, lua, luajit, api gateway, api management.

There is a Rust component too, which is easy to miss. `Cargo.toml` at the root defines a binary called `envoy-config-wrapper` built from `src/api-umbrella/bin/envoy-config-wrapper.rs`, with a release profile that sets `panic = "abort"` and strips symbols. The repository holds both `Cargo.toml` and `Cargo.lock`, so that wrapper is version pinned rather than ad hoc.

For anyone deciding whether this is a reasonable thing to operate, that list is the answer. Seven services with three different runtimes is a real operational surface, and it is the price of the feature set the README advertises.

Three services in the compose file, and the ports they use

`docker-compose.yml` is the development environment, and it names the dependencies outright: an `app` service, `postgres`, and `opensearch`.

    environment:
      HTTP_PORT: 8200
      HTTPS_PORT: 8201
      SECRET_KEY: for-development-not-secure

The literal value of `SECRET_KEY` is the detail to notice. It is a placeholder that says out loud it is not secure, which is a reasonable thing for a development compose file and a reminder that the real deployment carries different requirements.

The app service builds from the `Dockerfile` with `target: test`, mounts the working directory at `/app`, and pulls a cached dev image when `DOCKER_IMAGE_CACHE_FROM` is set. Postgres is published on host port 14011 and OpenSearch on 14002, both remapped away from their defaults so they do not collide with a local install. The OpenSearch service sets a small heap, disables the demo configuration, the security plugin and the performance analyzer agent, and runs single node with the disk threshold allocation check turned off.

The `Dockerfile-opensearch` and `Dockerfile-postgres` files at the root confirm those two are built rather than pulled, so the compose file describes a genuinely self contained development stack.

A build system assembled by configure, make and Task

The repository root is unusual in a way that tells you how the project is developed. Alongside the ordinary directories there is a `configure` script, a `Makefile.in`, a `Taskfile.yml`, a `Thorfile`, a `Jenkinsfile` and a `build/` directory. The Dockerfile copies `Makefile.in`, `Taskfile.yml` and `configure` into the image and then runs `./configure`, so configuration is a real step rather than an environment variable convention.

Task files under `tasks/` are organised by purpose, with entries like `tasks/deps/openresty`, `tasks/deps/envoy`, `tasks/build-deps`, `tasks/app-deps/example-website/pnpm` and `tasks/clean/dev`. The dependencies themselves are fetched by make targets that the Dockerfile invokes individually, which means each one can be rebuilt in isolation. Patches for openresty and trafficserver live under `build/patches/` and are copied in before the build, so the project carries local modifications to two of its dependencies.

Alongside that, `src/api-umbrella-git-1.rockspec` and `src/luarocks.lock` pin the Lua side, and the Rails web application has its own package manifest for the example website. The result is a dependency graph that is fully pinned and fully scripted, which is exactly what you want and exactly what makes it slow to change.

Other root files worth noting: `.luacheckrc` and `.rubocop.yml` for the two languages, `locale/` for translations, `templates/` for generated config, `db/` for migrations, `sha256sums.txt` for verification, and `docker-compose.ci.yml` alongside the development compose file.

Seven years between the last tag and the last push

This is the fact that most affects how you should read the rest. The most recent GitHub release is v0.15.1, published 2019-05-14, whose notes apologise for the gap since the previous formal release and describe a sizable upgrade. Before that sit v0.14.4 from 2017 and v0.14.3 from 2017-07-13. The repository, however, was last pushed on 2026-09-26, and it carries 2,198 stars, 373 forks and 256 open issues.

Both statements are true at once and they point in opposite directions. The code is being changed; no version has been cut since 2019. For an infrastructure platform whose upgrade path is documented per release, that gap is the thing to plan around. If you deploy from a tag you are deploying 2019 code. If you deploy from the default branch you are deploying code that no release notes describe.

The open issue count reinforces it. 256 open issues on a project of this type is a queue you should read before adopting, since reports about dependency breakage after years of no release tend to accumulate there.

There is a smaller wrinkle in the README itself. Its documentation and file links point at the `NREL/api-umbrella` path on GitHub, while this repository sits under a different organisation, `natlabrockies`. The Read the Docs links still resolve, but if you are following a repository link from the README you will land somewhere that is not this checkout.

Who it is for, and what to read first

The README names three users: api.data.gov, the NREL Developer Network, and api.sam.gov. All three are government API programmes, which is the most informative single fact about the project's priorities. Public sector API programmes need key management, per consumer rate limits, audit-friendly analytics and documentation that non technical consumers can follow, and that set of requirements explains a lot about the architecture.

The README also asks users to edit the file to add themselves, which is a small sign of how the project has grown.

Everything operational lives off the repository. There is a getting started guide, a developer setup guide for a local environment, and both on api-umbrella.readthedocs.org. The README is an argument for the idea, not an installation guide, and it does not pretend otherwise: no ports, no services, no upgrade path.

So the sensible order is the docs first for the concept and the deployment model, then `Dockerfile` and `docker-compose.yml` for the reality of the stack, then `CHANGELOG.md` for how far the default branch has moved since v0.15.1.

Editorial conclusion

API Umbrella's bet is that a layer above your APIs should not require changing your APIs, and the build system is the clearest evidence of what that costs: OpenResty, Envoy, Traffic Server, fluent-bit, LuaRocks, a Rails web application, Postgres and OpenSearch, plus a small Rust binary, all pinned by a Makefile and a Taskfile. If you are evaluating it, the honest questions are about deployment rather than features, and the README answers none of them: the last tagged release is v0.15.1 from 2019-05-14 while the repository was pushed on 2026-09-26, and 256 open issues is a large queue. Start with the getting started guide on readthedocs, then read `Dockerfile` and `docker-compose.yml` to see the services you would actually be running.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. NatLabRockies/api-umbrella on GitHub
4. README
5. Releases