Developers

On this page
Using the API

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 code by 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.