Practice: REST APIs, JSON and OAuth 2.0 authentication
Generated by Claude through GigAI 0.1.11.10 on 2026-10-11.
Main tool: JSON · JSON with JSON Schema is the language-neutral contract that every part of this lesson reduces to, so writing schemas for response bodies, token payloads, paged lists and writeback requests exercises the whole integration surface on a laptop. · Alternatives: OpenAPI describes whole HTTP endpoints, parameters and security schemes and embeds JSON Schema for the bodies; Pydantic validates the same shapes as Python classes at runtime and can emit JSON Schema; Zod does the same in TypeScript with inferred types; hand-written checks in a requests or httpx client need no extra tool but leave no shareable contract.
Every step links into the tool's own documentation; links were checked on 2026-10-11 · version 1
Setup (one time)
1. Read how JSON Schema describes and checks JSON documents before installing anything.
The path treats every HTTP body and token payload as a JSON instance checked against a schema, so the vocabulary of schema, instance and validation has to be clear first.
Explained in: JSON Schema - What is JSON Schema? (json-schema.org), checked 2026-10-11
Done when: You can say in one sentence each what a schema, an instance and a validation result are.
2. Install one command-line or library validator for your preferred language from the tooling list, choosing one that supports the 2020-12 dialect.
A validator is the only runtime this path needs, and picking one that supports the current dialect avoids confusing keyword mismatches later.
Explained in: JSON Schema - Tools (json-schema.org), checked 2026-10-11
Done when: The validator prints its version or help text when you call it from a terminal.
3. Install an editor or editor plugin with JSON Schema support from the tooling list and open an empty project folder with separate folders for schemas and sample payloads.
Inline completion and error squiggles shorten the feedback loop when writing schemas by hand. Keeping schemas apart from captured payloads makes later comparison and automation simpler.
Explained in: JSON Schema - Tools (json-schema.org), checked 2026-10-11
Done when: The editor offers keyword completion when you start typing inside a new schema file.
4. Decide on one dialect for the whole project and note the schema keyword value you will put at the top of every schema file.
Validators behave differently per dialect, and an integration that mixes drafts produces failures that are hard to trace.
Explained in: JSON Schema - Dialect and vocabulary declaration (json-schema.org), checked 2026-10-11
Done when: A short project note records the single dialect identifier every schema will declare.
Steps
1. Create your first schema file for one resource returned by an API you know, such as a customer or a ticket, with the dialect, an identifier, a title and a type.
This is the first run: the smallest schema that a validator accepts. Starting from a real resource keeps the exercise tied to consuming an existing API.
Explained in: Creating your first schema (json-schema.org), checked 2026-10-11
Done when: The validator loads the schema file without reporting a schema error.
2. Define the properties of that resource and mark which are required and which are optional, based on what the API actually returns rather than what its documentation claims.
Required versus optional is where imperfect third-party APIs bite most often. Writing it down turns an assumption into a testable contract.
Explained in: Creating your first schema (json-schema.org), checked 2026-10-11
Done when: The schema lists every field you depend on, with a required list that matches the fields your client cannot work without.
3. Run the validator against one saved good response and one deliberately broken copy with a missing field and a wrong type.
Seeing both a pass and a precise failure message proves the schema constrains something. It is also the habit that catches payload drift before it reaches a system of record.
Explained in: Creating your first schema (json-schema.org), checked 2026-10-11
Done when: The good payload passes and the broken one fails with a message naming the offending field.
4. Write a second schema for the error body the same endpoint returns on client and server errors, using an enumerated list for the error codes you have observed, and validate one captured error response per status class.
From the consumer side, HTTP semantics means the status code decides which body shape to expect. A client that only models the success body crashes on the first 4xx or 5xx.
Explained in: JSON Schema Validation: A Vocabulary for Structural Validation of JSON (json-schema.org), checked 2026-10-11
Done when: You have one schema per status class and each captured response validates only against the schema for its own status code.
5. Write a schema for the token request body that uses conditional keywords so that each grant type demands its own fields, for example a code and a code verifier for authorization code with PKCE, and a client secret only for client credentials.
Encoding the grant types as conditions forces you to state which role sends which parameters. It makes the difference between delegated user access and machine access explicit and checkable.
Explained in: JSON Schema - Conditional schema validation (json-schema.org), checked 2026-10-11
Done when: A sample request for each grant type passes, and a request that mixes fields from two grant types fails.
6. Write a schema for the token response with a required access token, a positive integer lifetime and a scope string, plus a schema for your client config file that accepts only the name of a secret store entry and never a raw secret value.
Token lifecycle bugs come from trusting the response shape, such as a missing lifetime or a narrower scope than requested. Validating the config file keeps secrets out of files that get committed.
Explained in: JSON Schema Validation: A Vocabulary for Structural Validation of JSON (json-schema.org), checked 2026-10-11
Done when: A response with a zero or missing lifetime fails, and a config file containing an inline secret value is rejected.
7. Write a schema for a paginated list envelope with an items array and a next cursor, and a schema for a batch writeback request whose idempotency keys must be unique within the array.
Pagination and writeback are where duplicates and silent truncation happen. A schema that rejects repeated keys and malformed page envelopes gives a resilient client a clear stop signal before it writes.
Explained in: JSON Schema Validation: A Vocabulary for Structural Validation of JSON (json-schema.org), checked 2026-10-11
Done when: A batch containing the same idempotency key twice fails validation and a page without a cursor field is handled by an explicit rule in the schema.
8. Create a shared schema file for the pieces reused across your contracts, such as the error object and the page envelope, and replace the copies with external references to it.
References are the core structuring mechanism of the schema object model and the same one OpenAPI uses for its components. Sharing definitions keeps five contracts from drifting apart.
Explained in: Creating your first schema (json-schema.org), checked 2026-10-11
Done when: All earlier sample payloads still pass after the duplicated definitions are replaced by references.
9. Run a data-to-schema generator from the tooling list over a folder of captured real responses and compare the generated schema with the one you wrote by hand.
Persisting real payloads and inferring a schema from them shows where the live API differs from your assumptions. The comparison is the evidence you bring to the API owner.
Explained in: JSON Schema - Tools (json-schema.org), checked 2026-10-11
Done when: You have a written list of at least the fields, types or optionality where the generated and handwritten schemas disagree, with each difference resolved.
10. Package the contracts by running a bundler from the tooling list to produce one self-contained schema document from the files that reference each other.
A single bundled document is what you hand to another team, attach to an OpenAPI description or load in a service that cannot resolve file references.
Explained in: JSON Schema - Tools (json-schema.org), checked 2026-10-11
Done when: The bundled file validates the same sample payloads with the original separate files removed from the search path.
11. Validate every schema file in the project against the general-purpose meta-schema of your chosen dialect.
Checking schemas against the meta-schema pins the dialect and catches misspelled or misplaced keywords, which validators otherwise ignore silently. It is the reproducibility check for the contracts themselves.
Explained in: JSON Schema - Specification [#section] (json-schema.org), checked 2026-10-11
Done when: Every schema passes the meta-schema check and a schema with a deliberately misspelled keyword location is reported.
12. Configure a linter from the tooling list and combine it with the meta-schema check and the sample payload validation in one script that runs locally the way a CI job would, in a container with pinned tool versions.
One repeatable command with pinned versions is what makes the contract enforceable on every change. It is the closest laptop equivalent of the gate a team runs before an integration ships.
Explained in: JSON Schema - Tools (json-schema.org), checked 2026-10-11
Done when: A single command exits successfully on the clean project and exits with a failure when you break one schema or one sample payload.