📒API Server and Base Path

✔️ API Server and Base URL

모든 API 엔드포인트는 base URL(server URL)의 상대경로다.

https://api.example.com/v1/users?role=admin&status=active
\________________________/\____/ \______________________/
         server URL       endpoint    query parameters
                            path

OpenAPI3.0에서는 API에 대한 여러 base URL들을 배열로 명시할 수 있다.

servers의 각 server는 url prefix를 반드시 가지고 있어야 한다.

description은 옵션이며, 마크 다운 형식이다.

servers:
  - url: https://api.example.com/v1    # The "url: " prefix is required

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 형식은 RFC 3986을 따른다.

scheme://host[:port][/path]

host는 domain name이나 IP주소(IPv4 or IPv6)로 표시한다. WebSocket의 scheme은 ws://그리고 wss://로 쓸 수 있다.

server URL이 상대경로라면 OpenAPI 정의 파일이 호스트 되는 서버의 baseURL에 연결된다.

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

servers 배열이 비어있는 경우 server URL의 기본값은 /다.

servers:
  - url: /

✔️Server Templating

server url의 scheme, host name, port, subpath 등을 변수를 사용해서 파라미터화 할 수 있다.

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'

변수는 server url에서 {}에 작성한다.

server variables는 schema를 사용하지 않고, 문자열로 간주됩니다.

또한 enum을 사용해서 사용 가능한 값을 제한할 수 있다.

어떤 경우라도 server variables는 default값이 반드시 필요하며, description은 선택입니다.

📌예시

👉HTTPS and HTTP

servers:
  - url: http://api.example.com
  - url: https://api.example.com

servers:
  - url: '{protocol}://api.example.com'
    variables:
      protocol:
        enum:
          - http
          - https
        default: https

👉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

global servers 배열은 path level 혹은 operation level에 의해 override될 수 있다.

몇몇의 endpoint들이 다른 서버나 다른 base path를 사용하는 경우 유용하게 사용할 수 있다.

• 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:
    get:
      servers:
        - url: https://echo.example.com
          description: Override base path for the GET /ping operation

✔️Relative URLs

servers 배열의 URL들은 상대경로로 작성할 수 있다.(예를 들어 /v2)

상대경로 URL은 OpenAPI 정의가 호스트되는 서버 경로에 붙는다. 즉, url의 상대 경로 사용시에는 OpenAPI 정의가 호스팅 되는 server url이 기준입니다.

예를 들어, http://localhost:3001/openapi.yaml에 호스트된 api 명세서에 url: /v2를 명시했다면, url은 http://localhost:3001/v2가 된다.

URL 상대경로 규칙은 RFC 3986을 따른다.

또한 API 명세서에서 모든 URL들(OAuth 2 flow endpoints, termsOfService, external documentation URL, ...등)은 모드 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