Guides

Versioning

The version is in the path: every endpoint starts with /v1. Every successful response also says which version answered, in meta.apiVersion.

What can change within v1#

Rankd adds to v1 without warning. Build your client so these do not break it:

• New endpoints.
• New fields in any object. Ignore fields you do not know.
• New feed card types. Skip types you do not know.
• New values where a field is a list of options, such as new music types. Treat unknown values gracefully.
• New optional query parameters.
• Different wording in error.message. Branch on error.code instead.

Breaking changes#

Removing or renaming a field, changing what a field means or its type, or removing an endpoint belongs in a new version, /v2, alongside v1. This site has a version selector at the top. When a v2 exists it will be listed there, with its own reference and a migration guide, and the changelog will say what changed.

Versions#