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 the
API reference. API v1’s schema (Swagger 2.0) is at
/api-docs/v1/openapi.json, with its own
reference.
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.
Each response object in the schema (Submission, Template and the rest) sets additionalProperties: true, so
clients generated from it accept new fields in them. The objects nested inside them (such as a template’s
document) keep additionalProperties: false, and a client that you
generate yourself may reject new fields in those. Enums in responses are
strings that list their current values in x-extensible-enum, so generated clients accept new values. Enums in
requests are strict: the API rejects a value it doesn’t know.