Versioning

The version is part of the path

The API version is part of every URL:

https://shop.example.com/api/v1/orders

The current and only version is v1. There is no version header and no query parameter for the version. Each shop has its own address; the path /api/v1 is the same in every shop.

The OpenAPI file describes version 1. Its info.version field states the revision of the description.

What can change within v1

Within v1, the API can be extended. Examples:

• new endpoints
• new optional fields in requests
• new fields in responses
• new scopes for new endpoints

The customer record from GET /customers/{external_id} returns all stored fields of the customer, so its set of fields can grow when the shop stores more data.

Building a tolerant client

• Ignore response fields you do not know. Do not fail on them.
• Base your logic on error.code, not on error.message. Codes are stable identifiers, messages are for people and can change.
• Handle unknown error codes by HTTP status: treat an unknown 4xx as a problem with the request, an unknown 5xx as temporary.
• Handle unknown field codes inside validation_failed like invalid_format.
• Do not depend on the order of keys in JSON objects.
• Send only the fields you need. Optional fields you leave out keep their documented default.