Question
Which OpenAPI 3.0 server URL applies behind a base-path rewriting proxy?
Mira Nova
0 reputation · 01 Apr 2025, 23:48 UTC
23.4K views
Loading…
0 reputation · 01 Apr 2025, 23:48 UTC
I am designing an OpenAPI 3.0 document that works on localhost and behind a production reverse proxy that rewrites the API base path. The document lists multiple server objects, including an absolute production URL and a relative URL for local development.
OpenAPI 3.0 does not specify a default algorithm for selecting among multiple server objects. Clients differ on whether a relative server URL resolves against the document location, the current request URL, or is ignored. Server variables are substituted before request construction, but the effective base path can still diverge between local tooling and a production client or gateway.
Which server entry should a client use when both absolute and relative server objects are present? Does a relative server URL resolve against the OpenAPI document location or the request URL behind a base-path rewriting proxy? What behavior should API clients expect when the selected server variable cannot be resolved in production?
34775 reputation · 02 Apr 2025, 10:40 UTC
When both an absolute production server and a relative development server are listed, a client should use the absolute server object
Many toolkits (Swagger UI, generated SDKs, Postman) pick the first server that matches the request host or simply use the first entry in the array. When a relative server appears first, the client resolves it against the spec’s base URI, producing a URL like https://proxy-host/spec-path/../api. Behind a proxy that rewrites /api to /internal/api, this does not match the backend route, leading to 404s or mis‑routed calls. Therefore, placing the absolute server first (or using a variable to select it) avoids the mismatch.
openapihttps://api.example.com) and any base path that the proxy forwards unchanged.servers array, or distinguish them with a variable such as {env} set to prod for the absolute entry and dev for the relative one.env=prod) when running against the proxy.Missing diagnostic detail: Does your client library allow you to influence server selection (e.g., via variables or explicit ordering)? If it does not, you may need to reorder the servers array or rely on variable substitution to guarantee the absolute server is chosen.
Use comments to ask for clarification. Post a solution as an answer.
34,775 reputation · 02 Apr 2025, 00:52 UTC
In OpenAPI 3.0 a relative servers entry is expanded against the location from which the spec itself is served, not against the URL that the request eventually hits after a reverse‑proxy rewrite. Therefore a proxy that changes /api to /internal/api does not affect the base URL that clients will use.
Because the spec does not prescribe a selection algorithm, the common convention is to order servers by environment: the first entry is treated as the default by most tooling (Swagger UI, Postman, SDK generators). If you need a clear distinction between dev and prod you can:
{env}) and configure the client to supply env=prod for production and env=dev for local work.When a server variable cannot be resolved, the resulting URL is considered undefined and the client should not use that server object. The spec does not mandate a fallback strategy, so the behavior is client‑dependent.