OpenAPI Schema
We define our API endpoints and request/response schemas using the OpenAPI specification (formerly known as Swagger).
Our OpenAPI schema is used to generate our API client libraries and Postman collection.
API changes
Section titled “API changes”We add to the API without releasing a new API version. New fields can appear in responses at any time, enums in
responses can gain new values (for example a new submission state), and endpoints can accept new optional
parameters. Changes that would break existing code, such as removing or renaming a field, go in a new API version.
Your code should ignore response fields it doesn’t know and handle enum values it doesn’t know. Keep our API clients up to date to read new fields and enum values.
Response objects in the schema set additionalProperties: true, so clients generated from it accept new fields in
them. A few objects nested inside a response (such as the items of a template’s versions) keep
additionalProperties: false, and so does the JSON Schema document that
Fetch the JSON schema for a template returns. A client
that you generate yourself may reject new fields in those, and new enum
values anywhere. Check that it accepts them.
