Versions

Every path starts with the API's major version, as in /v1/websites. The current version is v1. Customers have built on it for years, and Silktide keeps it backward compatible.

What Silktide promises#

• Documented v1 operations only gain things: new operations, new optional parameters, new fields in responses.
• Removing or renaming a documented field or operation needs notice. It is marked Deprecated on its page and in the changelog, with what to use instead, at least six months before it changes.
• Undocumented routes and fields can change at any time. If it is not on this site, do not build on it.

What to allow for#

Within v1, Silktide may also:

• Add values to a field that already lists several, such as a new score id.
• Change the wording of error messages.
• Refuse a request it used to answer wrongly. A mistake that once failed with 500 may fail with 400 instead, which is what it always meant.

Write your code to allow for these: ignore fields you do not know, and branch on an error's type, never its message.

Beta operations#

An operation marked Beta is new, and may still change shape before it is stable. Its page says so. The promise above covers it once it is stable.

Hearing about changes#

The changelog lists every change to the API, newest first, with the version that brought it. Every operation's page says the version it arrived in. Follow the changelog's Atom feed to hear about new operations and deprecations as they are published.