Versioning

API version#

The version of the API is the first segment of the path: /v1. Every endpoint in the API reference is in version 1. The API has no version header.

Changes without a new version#

Merxian can make these changes to /v1 at any time:

• Add an endpoint.
• Add an optional request field or parameter.
• Add a field to a response.
• Add a value to an enum, such as a new state or a new error code.
• Add a response header.

Your integration must continue to work after these changes:

• Ignore response fields that you do not know.
• Handle an enum value that you do not know. For a state, treat it as not final.
• Do not fail on a new error code. Use the HTTP status to decide what to do.

Webhook payload versions#

Each webhook event has an api_version field. It names the version of the payload shape.

The version is set on an endpoint when you create the endpoint. It does not change afterwards. All events to that endpoint use the same version.

To move to a newer payload version:

1. Create a new endpoint. It gets the current version.
2. Deploy code that handles the new payload.
3. Delete the old endpoint when the new one works.

During the change, both endpoints receive events. Use the event id to process each event once. See Process events.

Changelog#

Merxian does not publish a changelog yet.

Next steps

• Requests and responses
• Configure an endpoint
• Receive events