reference appendices

API Specification Checklist

Use This Reference When

Designing a JSON API boundary.
Reviewing backward compatibility.
Generating documentation or client tooling.

Endpoint Review

method and path
request parameters and body schema
authentication requirement
success status and response schema
validation and authorization errors
stable example payloads

A generated specification is only useful when it reflects runtime behaviour. Keep contract tests or review checks close to the implementation.

Practice

Specify One Endpoint

Write a compact contract checklist for POST /products, including success and validation failure responses.

Show solution

Record the request fields, authentication rule, 201 response shape, 422 validation error shape, and an example. Include any idempotency or authorisation behaviour relevant to the endpoint.