API Host and Base Path

REST APIs have a base URL to which the endpoint paths are appended. The base URL is defined by schemes, host and basePath on the root level of the API specification.

1
host: petstore.swagger.io
2
basePath: /v2
3
schemes:
4
    - https

All API paths are relative to this base URL, for example, /users actually means <scheme>://<host>/<basePath>/users.

URL structure

schemes

schemes are the transfer protocols used by the API. Swagger supports the http, https, and WebSocket schemes – ws and wss. As with any lists in YAML, schemes can be specified using the list syntax:

1
schemes:
2
    - http
3
    - https

or the array literal syntax:

1
schemes: [http, https]

If schemes are not specified, the scheme used to serve the API specification will be used for API calls.

host

host is the domain name or IP address (IPv4) of the host that serves the API. It may include the port number if different from the scheme’s default port (80 for HTTP and 443 for HTTPS). Note that this must be the host only, without http(s):// or sub-paths. Valid hosts:

1
api.example.com
2
example.com:8089
3
93.184.216.34
4
93.184.216.34:8089

Incorrect:

1
http://api.example.com
2
example.com/api/v1

If host is not specified, it is assumed to be the same host where the API documentation is being served.

basePath

basePath is the URL prefix for all API paths, relative to the host root. It must start with a leading slash /. If basePath is not specified, it defaults to /, that is, all paths start at the host root. Valid base paths:

1
/v2
2
/api/v2
3
/

Incorrect:

1
v2

Omitting host and scheme

host and schemes can be omitted for a more dynamic association. In this case, the host and scheme used to serve the API documentation will be used for API calls. For example, if Swagger UI-based documentation is hosted at https://api.example.com/apidocs/index.html, “try it out” API calls will be directed to https://api.example.com.

FAQ

Can I specify multiple hosts, e.g. development, test and production?

Multiple hosts are supported in OpenAPI 3.0. 2.0 supports only one host per API specification (or two if you count HTTP and HTTPS as different hosts). A possible way to target multiple hosts is to omit the host and schemes from your specification and serve it from each host. In this case, each copy of the specification will target the corresponding host.

Do host and basePath support templating? Such as:

1
https://{customer_id}.saas-app.com/api/v1
2
https://api.saas-app.com/v1/{customer_id}/apis

This is supported in OpenAPI 3.0, but not in 2.0. For a workaround for host templating, see the previous question.

Can I specify different ports for HTTP and HTTPS? Such as:

1
http://example.com:8080
2
https://example.com:8443

This is supported in OpenAPI 3.0, but not in 2.0. In 2.0, you can omit the host and schemes and serve the specification from both hosts. This way, each copy of the specification will target the host and port used to access that specification.

Reference

host, basePath and schemes fields

Did not find what you were looking for? Ask the community
Found a mistake? Let us know