The Servers Object — Defining API Base URLs and Environments

In this tutorial, you will learn about The Servers Object. We cover key concepts, practical examples, and best practices to help you master this topic.

The servers object in OpenAPI specifies the base URLs for the API, supporting multiple environments, variable substitution, and description annotations for each server.

In this tutorial, you will learn how to configure the servers object with multiple environments, use variables for dynamic URLs, and document server-specific details.

What You'll Learn

You will learn how to define server URLs, configure multiple environments, use server variables for dynamic values, and document server-specific behavior.

Why It Matters

Developers need to know where to send API requests. The servers object tells tools and developers the base URL for every environment. Well-configured servers enable one-click environment switching in interactive documentation.

Real-World Use

DodaTech defines three servers in every spec: production, staging, and local. The production URL is the default. Developers can switch environments in Swagger UI dropdown to test against different servers.

flowchart LR
  A[Servers Object] --> B[Production]
  A --> C[Staging]
  A --> D[Development]
  A --> E[Local]
  B:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Basic Server Definition

Each server has a url and optional description:

servers:
  - url: https://api.dodatech.com/v1
    description: Production server
  - url: https://staging-api.dodatech.com/v1
    description: Staging server
  - url: http://localhost:3000/v1
    description: Local development server

Server Variables

Server variables allow dynamic URL components:

servers:
  - url: https://{environment}.dodatech.com/v1
    description: Dynamic environment selection
    variables:
      environment:
        default: api
        description: Deployment environment
        enum:
          - api
          - staging-api
          - dev-api
  - url: https://api.dodatech.com/{version}
    description: Dynamic version selection
    variables:
      version:
        default: v1
        enum:
          - v1
          - v2
          - v3
        description: API version

Variable fields:

• default: the default value (required)
• description: explanation of the variable (optional)
• enum: list of allowed values (optional)

Single Server with Path Prefix

Some APIs use a single server with varying path prefixes:

servers:
  - url: https://api.dodatech.com
    description: DodaTech API root
  - url: https://api.dodatech.com/v1
    description: Version 1
  - url: https://api.dodatech.com/v2
    description: Version 2

Multi-Region Servers

Use variables for multi-region deployments:

servers:
  - url: https://{region}.api.dodatech.com/v1
    description: Regional deployment
    variables:
      region:
        default: us-east
        enum:
          - us-east
          - us-west
          - eu-west
          - ap-southeast
        description: AWS region for data locality

Server-Specific Behavior

Document differences between servers in descriptions:

servers:
  - url: https://api.dodatech.com/v1
    description: |
      Production server for live traffic.

      **Rate limit**: 200 requests/minute
      **Data**: Real customer data
      **SLA**: 99.99 percent uptime
  - url: https://staging-api.dodatech.com/v1
    description: |
      Staging server for integration testing.

      **Rate limit**: 1000 requests/minute
      **Data**: Synthetic test data
      **Note**: Reset nightly
  - url: http://localhost:3000/v1
    description: |
      Local development server.

      **Setup**: See docker-compose.yml
      **Data**: Empty database, run seed script

Common Mistakes

1. Missing servers entirely — Not defining any servers. Tools cannot make test requests without server URLs.

2. No description — Listing URLs without explaining which environment each represents. Always describe the server purpose.

3. Trailing slashes — Including trailing slashes in the URL. Servers base URL should not end with a slash.

4. Overly specific URLs — Hardcoding environment-specific details in the URL. Use variables for flexibility.

5. Only production server — Defining only the production URL. Include staging and development servers for testing.

Practice Questions

1. What fields does a server object have?
2. How do you define server variables?
3. Why should you include multiple server environments?
4. How do server variables improve flexibility?
5. What information should server descriptions include?

Challenge

Design a servers configuration for a global SaaS API with deployments in three regions (US, EU, APAC) and three environments (production, staging, development). Use server variables for region selection. Include meaningful descriptions that document rate limits and data handling for each environment.

FAQ

Mini Project

Create a servers configuration for a microservice API that has three services (users, documents, payments) each with three environments. Use server variables to let developers switch between service and environment. Validate the configuration with an OpenAPI validator.

What's Next

In the next lesson, you will learn how to define paths and operations in OpenAPI, including HTTP methods, operation IDs, and parameter definitions.