Compatibility
What can change in the API without a new version.
The version is in the path: /v1/. These changes are not breaking and can arrive at any time, so write your client to accept them:
- new resources and endpoints;
- new optional request parameters;
- new properties in a response;
- a different order of the properties in a response;
- new enum values;
- a different length or format of opaque strings, including id prefixes;
- different error messages. Branch on
code, never onmessage.
Deprecation
A deprecated operation announces it in its responses, with at least 12 months of notice:
Deprecation: @1798761600
Sunset: Sat, 01 Jan 2028 00:00:00 GMT
Link: <https://rarity.dev/docs/changelog>; rel="deprecation"Browsers can read all three headers.
Before the first external integration
Rarity has no active external integration yet, so a breaking change can still ship without a deprecation window. Each one has an entry in the changelog, marked Breaking.