URL versions

While Mambo uses the Accept-Version header for data model versioning, you'll also notice version numbers in our API URLs (e.g., v1, v2). These serve a different purpose than the versioning system described in the main versioning documentation.

URL versioning vs header versioning

Mambo uses two complementary versioning approaches:

1. Accept-Version header: Controls the data structure format (request/response models)
2. URL path versioning: Used when we need to re-engineer an endpoint in a non-backward compatible way

URL versioning is used less frequently but may be necessary when an endpoint's functionality changes significantly.

Endpoint deprecation process

When we need to create a new URL version of an API endpoint, we will:

1. Move the API to a new URL path with an incremented version number
2. Mark the previous version as deprecated
3. Provide advance notice through our communication channels
4. Maintain the deprecated endpoint for a reasonable transition period

You'll always receive clear communication about these types of changes to give you sufficient time to update your integrations.

You can see all recent deprecations in the deprecation changelog.

Example API endpoint

HTTP

GET /v1/{site}/users HTTP/1.1
Host: api.mambo.io
Accept-Version: 8.1.0

In this example:

• /v1/ indicates the URL path version
• Accept-Version: 8.1.0 specifies the data model version