Memojin
Log in

Versioning and deprecation

What may change within /v1 and what never does, the Memojin-Version header, Deprecation and Sunset, and 12 months of overlap with a future /v2.

api.memojin.com/v1 · Contract 1.0.0-beta.2 · Beta

Sections · Versioning and deprecation
On this page
  1. What may change within /v1
  2. What never changes within /v1
  3. The Memojin-Version header
  4. Deprecation and /v2
  5. During the beta

The major version is in the path: /v1. An integration written for /v1 keeps working, unchanged, as long as /v1 exists.

What may change within /v1

  • New operations, new scopes.
  • New optional parameters, new response fields.
  • New enum values (a status, a job type), new error codes for new cases.

What never changes within /v1

  • An operation, a field or a scope does not disappear, nor change its name or type.
  • An optional parameter does not become required; a validation does not get stricter.
  • An error code keeps its meaning.

The Memojin-Version header

Every response carries Memojin-Version, the version of the contract that served it (a beta version today, 1.0.0-beta.N). Quote it with X-Request-Id when you report unexpected behaviour.

Deprecation and /v2

If a breaking change becomes necessary, it ships in a new version, /v2, and /v1 keeps working for at least 12 months afterwards. An operation scheduled for removal is marked deprecated in the contract and answers with:

HTTP/1.1 200 OK
Deprecation: @1798761600
Sunset: Wed, 01 Mar 2028 00:00:00 GMT
Link: <https://memojin.com/developers/documentation/versioning>; rel="deprecation"

Deprecation (RFC 9745) dates the deprecation, Sunset (RFC 8594) the removal, Link leads to the migration guide. The organizations still calling it are warned by e-mail.

During the beta

The API is in beta: the 1.0.0 contract will be frozen before the first live key is opened, and the compatibility rule above applies from then on. Until then, every change is dated in the changelog.