ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-148] Server ​

Overview ​

The Server header is used to indicate the name and version of the server software handling the response. For API design, it should provide the API name and version information.

Guidelines ​

  • It MAY include the Server header in the response to provide information about the API server. For example: MY-OPENAPI/1.0.0.
  • It SHOULD NOT expose too much information about the actual operating system of the server in production environments to reduce potential security risks. DON'T DO THIS: Ubuntu/18.0.0.

OpenAPI Specification ​

Here is an example of how to document the Server header in OpenAPI:

yaml
components:
  headers:
    Server:
      description: Indicates the software used by the origin server to handle the request.
      schema:
        type: string
        example: "MY-OPENAPI/1.0.0"

TIP

According to ADP-767, you SHOULD use the already defined shared header file or at least use #/components/headers to avoid redefining all known headers.

Examples ​

Real-World Examples ​

  • In the HTTP API response of Microsoft Outlook web, you will see Server: Microsoft-HTTPAPI/2.0.
  • For GitHub, it is: Server: GitHub.com.

References ​