A lot of engineering teams treat OpenAPI as paperwork. The spec gets updated at the end, the examples go stale, and everyone agrees the code is the real source of truth.

I think that view misses what good API contracts actually do. In gateway products, the spec is often the clearest expression of what the platform wants developers to believe.

That is why openapi.yaml in this repo is more interesting than it looks.

This service is documenting two products at once

The gateway exposes a native Valhalla-style API surface and a Mapbox-compatible Directions endpoint. Those are not just two routes. They are two integration stories.

The OpenAPI spec tells developers:

  • this is one hosted service
  • here is how auth works
  • here are the public system endpoints
  • here is the compatibility surface you can target if you already speak Mapbox

That matters because a gateway like this is not just forwarding traffic. It is trying to become the stable contract in front of a more complicated backend topology.

Why this is product work

Once you publish a contract, you are making a promise about more than field names.

You are promising things like:

  • which endpoints are public and which are protected
  • what shape errors take
  • which query parameters are worth supporting long-term
  • how much compatibility developers can rely on

In other words, your spec is part of your distribution strategy.

For a product trying to attract developers, that is huge. A clear contract lowers trial friction, makes integration easier, and gives people confidence that the service was designed intentionally.

What I like in this spec

I like that /health and /metrics are explicitly marked with empty security requirements. I like that the Mapbox-style route is documented with parameter enums and examples. I like that the API key scheme is described clearly instead of being buried in prose.

Those details matter because developers do not experience your architecture directly. They experience your contract.

I also like that the existence of a compatibility endpoint is visible in the spec itself. That sends a strong message: this service understands migration and interoperability as first-class concerns.

Where specs usually drift

The hard part is keeping documentation honest when runtime behavior has nuance.

In this codebase, some of the most interesting nuances live outside the raw endpoint descriptions:

  • cross-region routing is orchestrated dynamically
  • some Mapbox-like features are best-effort translations, not exact equivalence
  • auth enforcement can move between app code and deployment boundary
  • rate limiting is documented as an operational topic, not just a response code

That is normal. A spec cannot hold every architectural detail. But when the gap between documented contract and lived behavior gets too large, developers stop trusting the spec.

What I would add

If I were polishing this for external adoption, I would add three things.

First, a short compatibility note describing which parts of the Mapbox surface are exact, which are approximate, and which are intentionally unsupported.

Second, clearer documentation around degraded states and upstream dependency behavior. Health endpoints are documented, but operational semantics are where production APIs often earn or lose trust.

Third, examples for common cross-region requests, because those are the requests that make this gateway special.

The lesson

OpenAPI is not just a generated artifact. It is one of the sharpest ways to communicate engineering intent.

In a system like this, the contract is doing real strategic work. It turns a multi-region routing architecture into something developers can adopt without learning the topology behind it. That is not paperwork. That is architecture translated into a usable product surface.