Versioning and stability

The version is in the path: every endpoint lives under /v1. Within v1, Postel only makes changes that keep working code working.

What can change in v1

• New endpoints.
• New fields in responses.
• New optional request parameters.
• New values in enums, such as a new network in platform, a new post status, a new event type or a new failure.type.
• New error codes.
• The wording of error messages.

What won't change in v1

• No field gets renamed, removed or changes its type.
• No required parameter gets added to an existing endpoint.
• No error code changes meaning.

A change that breaks any of these ships as /v2, next to v1. The changelog lists every change.

Write code that keeps working

• Ignore fields you don't know. Don't fail when a response has more fields than you expect.
• Handle enum values you don't know. Fall back to a default instead of crashing, for example when a new network shows up in GET /v1/channels.
• Branch on code, never on the error text.
• Treat ids and cursors as opaque strings.