API Server and Base Path

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 /:

1
servers:
2
  - url: /

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

Server Object

Relative References in URLs

Did not find what you were looking for? Ask the community Found a mistake? Let us know