API Server and Base Path

API Server and Base URL

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


   https://api.example.com/v1/users?role=admin&status=active
\________________________/\____/ \______________________/
         server URL       endpoint    query parameters
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
   
   .
   
    servers:
  - url: https://api.example.com/v1    # The "url: " prefix is required
   
   You can also have multiple servers, for example, production and sandbox:
   
    servers:
  - url: https://api.example.com/v1
    description: Production server (uses live data)
  - url: https://sandbox-api.example.com:8443/v1
    description: Sandbox server (uses test data)
   
   
    Server URL Format
   
   Server URL format follows
   
    RFC 3986
   
   and usually looks like this:
   
    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:
   
    https://api.example.com
https://api.example.com:8443/v1/reports
http://localhost:3025/v1
http://10.0.81.36/v1
ws://api.example.com/v1
wss://api.example.com/v1
/v1/reports
//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:
   
    https://api.example.com/v1
    
     ?route=
    
   
   If the
   
    servers
   
   array is not provided or is empty, the server URL defaults to
   
    /
   
   :
   
    servers:
  - 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:
   
    servers:
  - url: https://{customerId}.saas-app.com:{port}/v2
    variables:
      customerId:
        default: demo
        description: Customer ID assigned by the service provider
      port:
        enum:
          - '443'
          - '8443'
        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
   
   
    servers:
  - url: http://api.example.com
  - url: https://api.example.com
   
   Or using templating:
   
    servers:
  - url: '{protocol}://api.example.com'
    variables:
      protocol:
        enum:
          - http
          - https
        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
   
   
    servers:
  - url: https://{environment}.example.com/v2
    variables:
      environment:
        default: api    # Production server
        enum:
          - api         # Production server
          - api.dev     # Development server
          - api.staging # Staging server
   
   
    SaaS and On-Premise
   
   
    servers:
  - url: '{server}/v1'
    variables:
      server:
        default: https://api.example.com  # SaaS server
   
   
    Regional Endpoints for Different Geographical Areas
   
   
    servers:
  - url: https://{region}.api.cognitive.microsoft.com
    variables:
      region:
        default: westus
        enum:
          - westus
          - eastus2
          - westcentralus
          - westeurope
          - 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.
   
   
    servers:
  - url: https://api.example.com/v1
paths:
  /files:
    description: File upload and download operations
    servers:
      - url: https://files.example.com
        description: Override base path for all operations with the /files path
  /ping:
      servers:
        - url: https://echo.example.com
          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.
   
    servers:
  - url: https://api.example.com
  - url: https://sandbox-api.example.com
# Relative URL to Terms of Service
info:
  version: 0.0.0
  title: test
  termsOfService: /terms-of-use
# Relative URL to external documentation
externalDocs:
  url: /docs
  description: Find more info here
# Relative URLs to OAuth2 authorization and token URLs
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth/dialog
          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