Loading published curriculum…

18 · Testing the complete backend / LESSON 93 OF 102

API documentation and consumer contracts

Documentation should describe behavior that automated tests can keep honest.

Before this lesson: Testing commits, rollback, and concurrent updates

Understand the topic

An OpenAPI document names routes, parameters, schemas, statuses, and authentication requirements. Include invalid-input and conflict responses, not only success. Examples should use synthetic data and explain how a client obtains credentials.

Contract tests verify producer and consumer agreement at a boundary. Version response changes carefully: removing fields or narrowing accepted inputs can break clients. Keep executable request examples and regenerate or verify documentation as part of the build.

EXAMPLE · YAML

openapi.yaml excerpt

openapi: 3.0.3
info:
  title: Study Tasks API
  version: 1.0.0
paths:
  /api/tasks/{id}:
    get:
      parameters:
        - in: path
          name: id
          required: true
          schema: {type: integer, format: int64}
      responses:
        "200": {description: Task returned}
        "401": {description: Authentication required}
        "404": {description: Task unavailable}

What to expect

A minimal structural starting point. The lab adds response schemas, security schemes, examples, and error bodies matching the implemented API.

YOUR TURN

Put it into practice

  1. 01Document task CRUD and authentication requirements in OpenAPI.
  2. 02Add schema validation or contract assertions against real endpoint responses.
  3. 03Verify: Every documented status and example matches tested behavior and contains no real user data.

Pass a quiz or complete a lab to check today’s streak. Each lesson counts once per day, including when you review it later.

UNDER THE HOOD

Build the mental model

Documentation should describe behavior that automated tests can keep honest.

  1. 01An OpenAPI document names routes, parameters, schemas, statuses, and authentication requirements. Include invalid-input and conflict responses, not only success. Examples should use synthetic data and explain how a client obtains credentials.
  2. 02Contract tests verify producer and consumer agreement at a boundary. Version response changes carefully: removing fields or narrowing accepted inputs can break clients. Keep executable request examples and regenerate or verify documentation as part of the build.
  3. 03Trace the example: A minimal structural starting point. The lab adds response schemas, security schemes, examples, and error bodies matching the implemented API.

A mistake worth avoiding

A frontend breaks because the backend renamed a response field without notice.

DEBUGGING ROOM

Something broke. Where do you look?

A frontend breaks because the backend renamed a response field without notice.

Before revealing the diagnosis, write down your first investigation step.

CHECK YOUR UNDERSTANDING

Should an API specification document only successful responses?

Choose one answer

BUILD IT YOURSELF

Document task CRUD and authentication requirements in OpenAPI.

  1. 1.Document task CRUD and authentication requirements in OpenAPI.
  2. 2.Add schema validation or contract assertions against real endpoint responses.
  3. 3.Reproduce this failure, then repair it: A frontend breaks because the backend renamed a response field without notice.

Acceptance checklist

Lab completion is your self-report. Knowledge checks do not certify project quality.

RETRIEVE IT FROM MEMORY

Should an API specification document only successful responses?

Revisit this lesson in three days after a successful check or lab.

Ready for the next step?

Every documented status and example matches tested behavior and contains no real user data.

Reading is separate from passing a knowledge check or completing a lab.

Go deeper · official references