API Servers

This page shows how to specify the server where the API can be accessed, which can contain multiple URLs and even variable portions.

The Server Object

The Server Object provides the base URLs where the API is being served. It can be found in the servers array present in the root OpenAPI Object, the Path Item Object and the Operation Object.

The edges marked with an asterisk are arrays.
The OpenAPI Object is explained in the Structure of an OpenAPI Description page.
The Paths, Path Item and Operation Objects are explained in the API Endpoints page.

Each element in a servers array is a Server Object providing, at least, a url field with the base URL for that server. An optional description aids in keeping server lists organized:

servers:
- url: https://europe.server.com/v1
  description: Server located in Germany.
- url: https://america.server.com/v1
  description: Server located in Atlanta, GA.
- url: https://asia.server.com/v1
  description: Server located in Shenzhen

Individual API endpoints (as specified in the Paths Object) are then appended to this URL to construct the full endpoint URL. For example:

servers:
- url: https://server.com/v1
paths:
  /users:
    get:

The above operation can be accessed by executing a GET request on the URL https://server.com/v1/users.

When multiple servers arrays are specified at different levels for a given operation, only the lowest level one is taken into account. For example, in this case:

servers:
- url: https://server1.com
paths:
  /users:
    get:
      servers:
      - url: https://server2.com

GET requests to the /users endpoint are served from https://server2.com and not from https://server1.com.

NOTE: When providing multiple servers in an OpenAPI Description (OAD) keep in mind that they should all provide the same API (since they are being listed in the same API description).

If the servers are used for different environments (for example Testing and Production), chances are that their APIs will be different and describing them in a single OAD will be complicated.

In these cases it is probably better to use different OADs, and even different API versions. Read the Reusing Descriptions page to learn how to avoid code duplication and maintenance costs in these scenarios.

Conversely, if no servers are provided, it is assumed that all API endpoints are relative to the location where the OpenAPI Description document is being served. Be aware that if your OAD is split across multiple documents, each endpoint id assumed to be relative to the document in which it is described. Describing a server ensures that your endpoints are the same regardless of how your OAD is organized.

Finally, the server URLs can contain variable portions, as shown next.

Server Variables

Server URLs can contain variables, delimited by curly braces {}:

servers:
- url: https://{username}.server.com:{port}/{version}

These variables must then be further detailed in the variables field. This field is a map pairing variable names (matching the ones in curly braces in the server’s url) and Server Variable Objects.

The Server Variable Object has the following fields:

• default (string): This is a mandatory field and it is the value that should be used if there is no other value to provide.
• enum (array of strings): If present, this array lists the valid values for the variable (and the default value must be in the array).
• description (string): Documentation always helps understand the purpose of a variable.

Therefore, the above example could be extended like this:

servers:
- url: https://{username}.server.com:{port}/{version}
  variables:
    username:
      default: demo
      description: This value is assigned by the service provider.
    port:
      enum:
        - "8443"
        - "443"
      default: "8443"
    version:
      default: v1

NOTE: The default variable value works differently than the default Schema Object value used in other parts of the OpenAPI Specification. The latter is optional, meaning that if a Schema Object value is not provided it should be assumed to be the default value. On the other hand, server variables must always be provided.

Summary

This page has shown that:

• Server lists can be provided through the servers array.
• This array is present at different levels (OpenAPI Object, Path Item Object and Operation Object) and only the innermost one is used.
• Server URLs can contain variables for further customization like https://{username}.server.com:{port}/{version}