Versioning and deprecation
How the Postforge API is versioned, what counts as a breaking change, and how much notice you get before one.
The API's version is in its path: /v1. Within a version, Postforge only makes changes that don't
break working integrations; anything that would break one is announced first.
Before version 1
Postforge is in development. Until version 1 of the product, the API can change without notice. The promises below start at launch.
What may change without notice
- New operations, resources and webhooks
- New optional request parameters and fields
- New fields in answers, and new values in lists of codes (
codein a problem, a status) - New problem
codes within an existingtype
Write clients that ignore fields they don't know.
Breaking changes
Removing or renaming an operation, field or parameter, making an optional parameter required, or changing what a field means is a breaking change. After launch:
| Change | Notice |
|---|---|
Removing or breaking one operation within /v1 | 6 months |
A new major version (/v2) | /v1 keeps working for 12 months next to it |
How deprecation is signalled
A deprecated operation is marked deprecated in the OpenAPI spec,
and every answer from it carries:
Deprecation: @1798761600
Sunset: Thu, 01 Jul 2027 00:00:00 GMT
Link: <https://postforge.dev/developers/versioning>; rel="deprecation", <https://postforge.dev/developers/versioning>; rel="sunset"Deprecation(RFC 9745): since when, as a Unix timestampSunset(RFC 8594): when it stops workingLink: the notice explaining what to use instead
Watch for these headers in your logs, and plan the move before the Sunset date.