Absolute vs Relative Server URLs for Multi-Environment Portability
25.6K 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?