Versioning
The version is part of every path: /v2/users/{username}. Nothing else chooses it.
The version is in the path
Every endpoint in this documentation starts with /v2/, so you don't need a version header. The API ignores X-Version on a /v2/ path: a client that still sends X-Version: 1.0 on every call can keep doing so. A path with another version, such as /v3/meta, is a 400 with no body: see Errors.
Successful responses carry an api-supported-versions header naming the versions the endpoint supports: today, 2.0.
What can change within version 2
Additions can arrive at any time, without notice, and are listed in the Changelog. A client should expect:
- New endpoints.
- New fields in responses, including inside objects you already read.
- New values where a field holds one of a set, such as a new error
code. - New optional parameters.
Changes that would break a working client come in a new version instead, with its own path. Breaking changes include removing or renaming a field or endpoint, changing what a field holds or means, and making an optional parameter required.
Write a client that keeps working
- Ignore fields you don't know, rather than failing on them. Most JSON libraries do this by default; check yours if you read into strict types.
- Handle values you don't know: treat an unknown error
codeby its HTTP status, for example. - Don't depend on the order of keys in an object.
- Keep cursors opaque. What's inside them can change at any time: see Paging.
The OpenAPI document behind the API reference describes version 2 as it is now. Use it to generate a client, or compare it with an earlier copy to see what was added.
Version 1
Version 1 still works for the apps that use it, with its own paths, such as /transmissions/{username}, and its own limits. New apps should use version 2. Moving from v1 maps each version 1 call to its version 2 replacement.