Contracts & knowledge · Specification
OpenAPI
Describe an HTTP API’s operations, inputs, responses, and security requirements.
What it helps you do
Give people and tools a shared interface description without requiring them to infer the API from implementation code.
Starting knowledge: Know the basics of HTTP requests, responses, and status codes.
- Describe paths and operations from the consumer’s perspective.
- Specify requests and relevant success and error responses.
- Keep authentication descriptions distinct from actual authorization enforcement.
The problem it came from
The OpenAPI Specification grew from the Swagger ecosystem and is maintained through the OpenAPI Initiative. It provides a language-independent description of HTTP interfaces.
This entry references OpenAPI 3.1.0, published in 2021, as a specific teaching baseline. It does not claim that this is the newest release.
Work through an example
openapi: 3.1.0
info:
title: Workshop API
version: 1.0.0
paths:
/registrations:
post:
responses:
"201":
description: New registration created
"400":
description: Registration input is invalid
# Minimal teaching document; request schemas and other outcomes
# must be added for a real registration contract.- The example names the HTTP operation.
- The response statuses distinguish creation from invalid input.
- The comment explicitly identifies what this minimal document leaves out.
Where it helps. Where it stops.
Use it when
- Designing or reviewing an HTTP interface.
- A payload schema exists but clients cannot tell where to send it or how failures are represented.
Potential benefits
- A shared contract supports documentation, tooling, and implementation review.
- Explicit failure responses expose missing behavior early.
Limits and common mistakes
- A specification can disagree with the running service.
- Security declarations describe requirements; they do not install enforcement.
The prompt below asks for this structure. It does not guarantee accuracy, complete coverage, better learning, or conformance to a standard. Treat those outcomes as separate checks.
Practise the judgment
Try a choice, inspect a boundary, then explain a case yourself. Hints and answers are available whenever you need them.
Which question needs OpenAPI beyond a payload schema?
Hint
Think about the consumer’s whole request.
Explained answer
Best answer for this case: Which HTTP operation accepts this payload and what errors can it return?
OpenAPI adds operation-level interface information around payload descriptions.
Does a security declaration in OpenAPI enforce access control?
Hint
Separate contract and implementation.
Explained answer
Best answer for this case: No; the server must implement enforcement
A description of a requirement does not perform the check.
What should a registration API describe when the input is missing required information?
Hint
What does a client need to recover?
Explained answer & self-review rubric
Describe the relevant client-error response and its payload, including how the missing information is identified. Agree the status and error semantics instead of assuming all failures return the same success shape.
- Include an error response
- Describe its body
- Avoid inventing unapproved semantics
Take it into your own work
Manual template
Use this structure yourself, with a colleague, or in your preferred writing tool.
# HTTP API contract
Specification version:
Consumer and purpose:
Path and HTTP method:
Parameters:
Request body and schema:
Success responses:
Error responses:
Authentication and authorization expectations:
Compatibility policy:
Implementation checks:
Review the result
- Are important failure responses described?
- Do request and response examples match the schemas?
- Has actual behavior been checked separately?
Use this approach with your own AI tool
Help me apply OpenAPI to the material below.
Reader and existing knowledge: [describe]
Task and desired outcome: [describe]
Use these principles: Describe paths and operations from the consumer’s perspective.; Specify requests and relevant success and error responses.; Keep authentication descriptions distinct from actual authorization enforcement..
Preserve source facts, identifiers, quantities, conditions, exceptions, and uncertainty.
Separate supplied facts from assumptions. Ask for missing information instead of inventing it.
Explain your representation choices and provide a review checklist. Do not claim formal compliance or correctness from formatting alone.
Material: [paste only information you are permitted to share]Go to the source
History and the underlying approach are grounded in these references. Examples, prompts, and practice cases here are original educational adaptations. Edition-specific details should be checked against the referenced publication.
Last editorial review: 2026-10-24. An overview is not certification, and this guide is not a reproduction of a standard.