Contract

Use these pages to write the contract. Each page is one task. They build on Write the contract.

• The shape of a contract: api, surfaces, collections, routes and how settings flow down the tree.
• Types and references: schemas, enums, optional and nullable, split files.
• Errors: declare a code, attach it, rename a built-in one.
• Access: public routes, identities and rights.
• Lists: paging styles, sorting, unpaged lists.
• Versioning and change: path version, maturity, deprecation.
• Advanced: uploads, downloads, lost updates, cache.

A snippet that starts at a route name goes under surfaces.<surface>.routes; one that starts at errors:, pagings: or schemas: is a top-level block. Each snippet names its place in a first-line comment.

Next: The shape of a contract. Every key is in the grammar.