API Server and Base Path (original) (raw)
All API endpoints are relative to the base URL. For example, assuming the base URL of https://api.example.com/v1, the /users endpoint refers to https://api.example.com/v1/users.
1
https://api.example.com/v1/users?role=admin&status=active
2
\________________________/\____/ \______________________/
3
server URL endpoint query parameters
4
path
In OpenAPI 3.0, you use the servers array to specify one or more base URLs for your API. servers replaces the host, basePath and schemes keywords used in OpenAPI 2.0. Each server has an url and an optional Markdown-formatted description.
1
servers:
2
- url: https://api.example.com/v1 # The "url: " prefix is required
You can also have multiple servers, for example, production and sandbox:
1
servers:
2
- url: https://api.example.com/v1
3
description: Production server (uses live data)
4
- url: https://sandbox-api.example.com:8443/v1
5
description: Sandbox server (uses test data)
Server URL Format
Server URL format follows RFC 3986 and usually looks like this:
1
scheme://host[:port][/path]
The host can be a name or IP address (IPv4 or IPv6). WebSocket schemes ws:// and wss:// from OpenAPI 2.0 are also supported in OpenAPI 3.0. Examples of valid server URLs:
1
https://api.example.com
2
https://api.example.com:8443/v1/reports
3
http://localhost:3025/v1
4
http://10.0.81.36/v1
5
ws://api.example.com/v1
6
wss://api.example.com/v1
7
/v1/reports
8
/
9
//api.example.com
If the server URL is relative, it is resolved against the server where the given OpenAPI definition file is hosted (more on that below). Note: Server URL must not include query string parameters. For example, this is invalid:
1
https://api.example.com/v1?route=
If the servers array is not provided or is empty, the server URL defaults to /:
Server Templating
Any part of the server URL – scheme, host name or its parts, port, subpath – can be parameterized using variables. Variables are indicated by {curly braces} in the server url, like so:
1
servers:
2
- url: https://{customerId}.saas-app.com:{port}/v2
3
variables:
4
customerId:
5
default: demo
6
description: Customer ID assigned by the service provider
7
port:
8
enum:
9
- '443'
10
- '8443'
11
default: '443'
Unlike path parameters, server variables do not use a schema. Instead, they are assumed to be strings. Variables can have arbitrary values, or may be restricted to an enum. In any case, a default value is required, which will be used if the client does not supply a value. Variable description is optional, but useful to have and supports Markdown (CommonMark) for rich text formatting. Common use cases for server templating:
- Specifying multiple protocols (such as HTTP vs HTTPS).
- SaaS (hosted) applications where each customer has their own subdomain.
- Regional servers in different geographical regions (example: Amazon Web Services).
- Single API definition for SaaS and on-premise APIs.
Examples
HTTPS and HTTP
1
servers:
2
- url: http://api.example.com
3
- url: https://api.example.com
Or using templating:
1
servers:
2
- url: '{protocol}://api.example.com'
3
variables:
4
protocol:
5
enum:
6
- http
7
- https
8
default: https
Note: These two examples are semantically different. The second example explicitly sets the HTTPS server as default, whereas the first example does not have a default server.
Production, Development and Staging
1
servers:
2
- url: https://{environment}.example.com/v2
3
variables:
4
environment:
5
default: api # Production server
6
enum:
7
- api # Production server
8
- api.dev # Development server
9
- api.staging # Staging server
SaaS and On-Premise
1
servers:
2
- url: "{server}/v1"
3
variables:
4
server:
5
default: https://api.example.com # SaaS server
Regional Endpoints for Different Geographical Areas
1
servers:
2
- url: https://{region}.api.cognitive.microsoft.com
3
variables:
4
region:
5
default: westus
6
enum:
7
- westus
8
- eastus2
9
- westcentralus
10
- westeurope
11
- southeastasia
Overriding Servers
The global servers array can be overridden on the path level or operation level. This is handy if some endpoints use a different server or base path than the rest of the API. Common examples are:
- Different base URL for file upload and download operations,
- Deprecated but still functional endpoints.
1
servers:
2
- url: https://api.example.com/v1
3
4
paths:
5
/files:
6
description: File upload and download operations
7
servers:
8
- url: https://files.example.com
9
description: Override base path for all operations with the /files path
10
...
11
12
/ping:
13
get:
14
servers:
15
- url: https://echo.example.com
16
description: Override base path for the GET /ping operation
Relative URLs
The URLs in the servers array can be relative, such as /v2. In this case, the URL is resolved against the server that hosts the given OpenAPI definition. This is useful in on-premises installations hosted on your customer’s own servers. For example, if the definition hosted at http://localhost:3001/openapi.yaml specifies url: /v2, the url is resolved to http://localhost:3001/v2. Relative URL resolution rules follow RFC 3986. Moreover, almost all other URLs in an API definition, including OAuth 2 flow endpoints, termsOfService, external documentation URL and others, can be specified relative to the server URL.
1
servers:
2
- url: https://api.example.com
3
- url: https://sandbox-api.example.com
4
5
# Relative URL to Terms of Service
6
info:
7
version: 0.0.0
8
title: test
9
termsOfService: /terms-of-use
10
11
# Relative URL to external documentation
12
externalDocs:
13
url: /docs
14
description: Find more info here
15
16
# Relative URLs to OAuth2 authorization and token URLs
17
components:
18
securitySchemes:
19
oauth2:
20
type: oauth2
21
flows:
22
authorizationCode:
23
authorizationUrl: /oauth/dialog
24
tokenUrl: /oauth/token
Note that if using multiple servers, the resources specified by relative URLs are expected to exist on all servers.
References
Did not find what you were looking for? Ask the communityFound a mistake? Let us know