Practice: API design
Generated by Claude through GigAI (karthik446/gigai-learning-center 4c0cb514) on 2026-10-13.
Main tool: OpenAPI · OpenAPI is the machine-readable contract format in which resources, parameters, error responses, callbacks and version metadata are all written down in one document, so every subtopic of this lesson can be practised by editing a single file on a laptop. · Alternatives: gRPC with Protocol Buffers gives a binary, strongly typed RPC contract instead of resource-style HTTP; GraphQL lets clients pick fields through one typed query endpoint rather than many resource paths; JSON Schema alone describes payload shapes but not paths, operations or status codes.
Every step links into the tool's own documentation; links were checked on 2026-10-13 · version 1
Setup (one time)
1. Choose the specification version you will write against and note its exact number for the rest of the path.
Every object and field you use later depends on the version you target. Fixing it first prevents mixing features from different releases.
Explained in: OpenAPI Specification (spec.openapis.org), checked 2026-10-13
Done when: You have written down one published specification version number that the whole practice contract will declare.
2. Create a new folder under version control with one empty YAML file that will hold the contract for a small orders API.
The contract is a text artefact that lives next to code and is reviewed like code. Starting in version control makes later comparisons possible.
Explained in: OpenAPI Specification v3.2.1 (spec.openapis.org), checked 2026-10-13
Done when: A repository exists with one committed, empty YAML contract file.
3. Download the published schema for your chosen specification version and wire it into a YAML-aware editor or a JSON Schema validator of your choice.
The published schema lets a local validator tell you at once when the document is structurally wrong. It is the fastest feedback loop for contract-first work.
Explained in: OpenAPI Specification (spec.openapis.org), checked 2026-10-13
Done when: Your editor or validator reports an error on the empty file because required fields are missing.
Steps
1. Write the smallest valid document: the specification version field, an info block and an empty paths block.
Contract-first design starts with a document that validates before any code exists. The root object shows which fields are required and which are optional.
Explained in: OpenAPI Specification v3.2.1 (spec.openapis.org), checked 2026-10-13
Done when: The validator reports no errors on the three-field document.
2. Write the info object with a title, a summary and an API version string that is separate from the specification version.
The info version is the version of your contract, the number clients will see and depend on. Keeping it distinct from the specification version is the basis of every later versioning decision.
Explained in: OpenAPI Specification v3.2.1 (spec.openapis.org), checked 2026-10-13
Done when: The document validates and shows two different version values, one for the specification and one for your API.
3. Create two templated paths for the orders resource: one for the collection and one for a single order identified by a path variable.
Resource-oriented modelling means the paths name nouns in the domain, not actions. Path templating is how one entry stands for every instance of a resource.
Explained in: OpenAPI Specification v3.2.1 (spec.openapis.org), checked 2026-10-13
Done when: The paths block holds a collection path and an item path with one named variable, and the validator accepts both.
4. Create the operations on each path item: list and create on the collection, then fetch, update and delete on the single order.
A small, consistent set of operations per resource is what makes an API predictable. The path item object shows which operations can hang off one path and what they share.
Explained in: OpenAPI Specification v3.1.0 (spec.openapis.org), checked 2026-10-13
Done when: Five operations exist across the two paths, each with a unique operation identifier, and the document validates.
5. Define the order schema, an order list schema and a shared error schema once in the components block and reference them from the operations.
Reusable components keep the contract consistent and make a change to a resource shape happen in one place. They are also what code generators and reviewers read first.
Explained in: OpenAPI Specification v3.2.1 (spec.openapis.org), checked 2026-10-13
Done when: No operation contains an inline copy of the order shape; each one points at a named component and the references resolve.
6. Configure query parameters on the list operation for a page cursor, a page size limit, a status filter and a field selection list for partial responses.
Large result sets must be bounded from the first release because adding pagination later breaks clients. The parameter object fixes each one's location, type, default and whether it is required.
Explained in: OpenAPI Specification v3.1.0 (spec.openapis.org), checked 2026-10-13
Done when: The list operation declares four optional query parameters with types and defaults, and the list schema carries a next cursor field.
7. Define the responses for every operation: the success codes, the specific client error codes and a default response that returns the shared error schema.
Status codes and the error body are part of the contract and are as hard to change as any field. A single error shape lets clients write one handler for every failure.
Explained in: OpenAPI Specification v3.1.0 (spec.openapis.org), checked 2026-10-13
Done when: Every operation lists at least one success code and a default error response that references the shared error component.
8. Write a long-running export operation that returns an accepted status with a job resource, and attach a callback that describes the webhook request your API sends when the job finishes.
Slow work should not hold a request open, so the contract must say how the client learns the outcome. The callback object documents the request your server makes to the client, which is the webhook half of the contract.
Explained in: OpenAPI Specification v3.1.0 (spec.openapis.org), checked 2026-10-13
Done when: The export operation shows an accepted response, a job status path exists, and a callback keyed on a client-supplied address validates.
9. Configure the server entry with a base path variable for the major version, giving it a default and an allowed list of values.
Where the version lives in the address is a design decision clients feel directly. A server variable makes that choice explicit and limits it to the versions you actually support.
Explained in: OpenAPI Specification v3.2.1 (spec.openapis.org), checked 2026-10-13
Done when: The server address contains one variable whose default and allowed values name your supported major versions.
10. Compare two saved revisions of your contract after adding an optional field and removing a required one, and label each change as patch, minor or major using the specification's own versioning scheme as the model.
Backwards compatibility is judged change by change, and the specification applies the same major, minor and patch discipline to itself. Practising the classification on your own diff is what turns the rule into a habit.
Explained in: OpenAPI Specification v3.2.0 (spec.openapis.org), checked 2026-10-13
Done when: The repository holds two tagged revisions and a short change note that marks the removed field as breaking and the added optional field as compatible.
11. Check every format value used in your schemas against the registered formats and replace any invented or ambiguous one, such as a money amount typed as a floating number.
Registered formats are the shared vocabulary that tools and other teams understand. A contract that only uses registered values is one that can be published and consumed without private explanations.
Explained in: Format Registry (spec.openapis.org), checked 2026-10-13
Done when: Each format in the document appears in the registry list, and money amounts use a registered fixed-point format.
12. Write a small check that parses the contract, confirms the pinned specification version, validates it against the published schema, and run it locally the same way a CI job would on every commit.
A contract that is only checked by hand drifts from the rules within weeks. Parsing the document the way the specification describes, on every change, makes the result reproducible on any machine.
Explained in: OpenAPI Specification v3.1.2 (spec.openapis.org), checked 2026-10-13
Done when: The check passes on the current contract and fails with a clear message when you deliberately break a reference or change the pinned version.