API versioning and deprecation policy

This policy applies to the ShowMojo REST APIs, the Leads & Showings webhook, and the Zapier integration. Changes are announced in the API changelog.

How versions work​

The API version is part of the URL path. Today these versions are live:

A new URL version is introduced only when a change cannot be made compatibly within the current version. Within a version, we only make the non-breaking changes listed below.

Each OpenAPI document also carries a version field that tracks the document itself: a patch bump for documentation-only clarifications, a minor bump for additive changes, and a major bump when a new URL version is introduced. Download the current documents from /openapi/showmojo-api-legacy.yaml, /openapi/showmojo-api-v4.yaml, and /openapi/showmojo-api-zapier.yaml.

Non-breaking changes​

These can ship at any time within a version. They are listed in the changelog but do not require a new version or a deprecation notice. Build your integration so that it tolerates them.

• Adding a new endpoint or a new HTTP method on an existing endpoint.
• Adding an optional request parameter or request body field.
• Adding a field to a response body or a webhook payload.
• Adding a new value to an enumerated field, such as a new external_source, fee type, or webhook event type.
• Adding a response header.
• Changing the text of a human-readable error message.
• Changing the order of fields in a JSON object or of items in an unordered list.
• Fixing behaviour that contradicts the documentation.

Breaking changes​

These never ship within a version without a deprecation period. Where a change cannot be made compatibly at all, it ships in a new URL version instead.

• Removing or renaming an endpoint, request parameter, request field, response field, or webhook payload field.
• Changing the type or format of a field, such as a string becoming an object or a timestamp changing format.
• Removing a value from an enumerated field.
• Making an optional request parameter or field required, or tightening validation so that previously accepted requests are rejected.
• Changing authentication requirements, such as removing a supported scheme.
• Changing the HTTP status code returned for an existing outcome.
• Changing webhook retry or signing behaviour in a way that requires receiver changes.

Deprecation process​

1. Announcement. The deprecation is listed in the changelog with the date it was announced, what replaces it, and the sunset date after which it stops working. The affected element is marked deprecated: true in the OpenAPI document, which also marks it in the generated documentation. A deprecated endpoint or URL version additionally returns Deprecation and Sunset response headers carrying the announcement and sunset dates.
2. Notice period. A deprecated endpoint, parameter, field, or header keeps working for at least 90 days after the announcement. A URL version keeps working for at least 12 months after its successor is marked stable.
3. Direct notice. Where ShowMojo can see which accounts still use a deprecated element, for example a webhook endpoint still receiving the deprecated Authorization header, the account owner is emailed before the sunset date.
4. Sunset. On or after the sunset date, the element is removed. A removed URL version responds with 404 Not Found.

Security fixes are the one exception: a change needed to close a vulnerability may ship with a shorter notice period. It is still announced in the changelog.

Current deprecations​

No URL version is scheduled for retirement.