Base URI and the trailing /

[nickevansuk]

Should Base URI contain a trailing /? The arguments are summarised as follows:

Option 1: Base URI should not include the trailing /

This is the approach taken by Open API 3, where the relative path is appended (no relative URL resolution) to the Base URI. Simple appending is straightforward to implement and unambiguous, and is likely most common amongst implementations.

The Base URI specified in the dataset site would exactly match any OpenAPI machine-readable documentation.

With this approach it is possible to specify behaviour for the path / (as it is not part of the Base URI), which is likely why this is favoured for API documentation such as OpenAPI.

Actions required

1. Specification should be updated: the Base URI MUST NOT include a trailing /.
2. The specification should be updated to reference Open API, and make the approach of appending the Base URI to the defined relative path clear.
3. Tooling must be updated to not use a trailing /.
4. Validator must ensure Base URIs do not include a trailing /.

Option 2: Base URL should include the trailing /

This approach follows RFC3986, which is already indirectly cited in the current version of the specification, and involves formal relative URL resolution. Relative URL resolution has broad library support, and is compatible with browser behaviour. Simple appending is still possible given the nature of the endpoints defined in the specification.

The Base URI specified in the dataset site would differ from any OpenAPI machine-readable documentation.

Actions required

1. Specification should be updated: the Base URI MUST include a trailing /.
2. Relative paths referenced in the specification should be updated to be compatible with relative URL resolution e.g. ./order-quote-templates/{uuid} or order-quote-templates/{uuid}
3. Validator must ensure Base URIs include a trailing /.

[nickevansuk]

A Google search for “api base url“ returns many examples, the vast majority of which follow the convention outlined by Option 1.

Hence this proposal is to proceed with Option 1, in line with broader conventions.

[nickevansuk]

Tooling has now been updated to reflect Option 1