Question
Absolute vs Relative Server URLs for Multi-Environment Portability
Rey Lane
0 reputation · 13 Nov 2020, 15:58 UTC
53.1K views
Loading…
0 reputation · 13 Nov 2020, 15:58 UTC
When defining the servers object in an OpenAPI Specification (OAS) 3.0.x, there is a trade-off between using absolute URLs and relative paths to ensure the API remains functional across local, staging, and production environments.
Absolute URLs provide explicit targeting and clarity for external clients but often require a build-step to swap environment-specific values before deployment to avoid hardcoding internal IPs or localhost addresses in production. Conversely, relative URLs (e.g., /v1) offer high portability by relying on the host where the documentation is served, though this can introduce ambiguity if the API gateway is hosted on a different domain than the UI.
Given these constraints, what are the implications for client-side request resolution when relative paths are used in conjunction with a separate API Gateway domain? Does the OAS specification provide a standardized way to prioritize these definitions when runtime overrides are applied by the hosting infrastructure?
34775 reputation · 13 Nov 2020, 21:48 UTC
When relative paths (e.g., /v1) are used in the servers object of an OpenAPI Specification (OAS), the client-side request resolution relies entirely on the origin of the document. If the OAS documentation UI is hosted on docs.example.com but the API Gateway is hosted on api.example.com, a relative path will resolve to docs.example.com/v1, resulting in a 404 or a CORS error.
Relative URLs are only portable when the API Gateway and the documentation UI share the same host and port. In a decoupled architecture where the Gateway is on a separate domain, relative paths break the request chain because the browser cannot automatically infer a different domain for the API target.
The OAS 3.0.x specification does not provide a built-in mechanism to prioritize server definitions based on runtime infrastructure overrides. The servers array is a static list of targets. The responsibility for selection falls into two categories:
openapiservers array as the default, but allow the base URL to be overridden programmatically during client instantiation.To maintain portability without hardcoding environment-specific IPs, use a combination of Server Variables and Environment Injection:
variables object within the servers array to parameterize the host.servers:
- url: https://{environment}.example.com/v1
variables:
environment:
default: api
enum: [local, staging, api]
default value or the entire servers block with the environment-specific absolute URL./v1 requests to the API Gateway domain at the infrastructure level (e.g., via Nginx or an Ingress Controller).To verify resolution behavior, perform the following checks in the browser developer tools:
Access-Control-Allow-Origin headers that explicitly permit the domain hosting the OAS UI.Diagnostic Detail Needed: Are you using a specific OAS UI renderer (e.g., Swagger UI, Redoc) or a custom-generated SDK? The method for overriding the base URL varies significantly between a browser-based UI and a compiled client library.
Use comments to ask for clarification. Post a solution as an answer.
34,775 reputation · 14 Nov 2020, 01:43 UTC
To expand on the resolution of relative paths, it is important to distinguish between the base path and the origin. While the previous response correctly identifies that relative URLs resolve to the document's host, this often creates a specific failure pattern in decoupled architectures: the CORS (Cross-Origin Resource Sharing) preflight check.
When a relative path is used and the UI is hosted on a different domain than the API, the browser attempts to send the request to the UI's own domain. If that domain happens to have a proxy configured to forward requests to the API Gateway, the request may succeed, but only if the proxy handles the OPTIONS method correctly. Without such a proxy, the request fails before it even reaches the Gateway.
For those using OAS 3.0.x, a practical verification step is to check the Network tab in browser developer tools. If the request URL matches the documentation URL rather than the intended API endpoint, the relative path is resolving to the origin, confirming that a separate absolute URL or a server variable is required for cross-domain portability.