Pepelen
← Systems Analysis: APIs, Integrations and Data

Lesson

OpenAPI: reading and writing an endpoint contract

Read an endpoint description in OpenAPI 3.1 — path, parameters, request body, responses with status codes and schemas — and write such a description for a new Romashka endpoint.

1 / 8

The contract everything else is built from

The contract everything else is built from

OpenAPI is a machine-readable REST API contract in YAML or JSON. One file gives you documentation, stubs (mocks), request validation and client code. The course uses version 3.1: its schemas are JSON Schema 2020-12 from the previous lesson. Version 3.2 (September 2025) is compatible with 3.1 and adds features; just know it exists. Contract-first (API-first): first the contract, agreed by frontend and backend, then the code, and the teams work in parallel. The top level of the document: • openapi — the specification version, for example 3.1.0; • info — the title, description and version of the API itself; • servers — base URLs: https://api.romashka.example/v1; • paths — resource paths and their methods; • components — shared schemas, responses and security schemes (securitySchemes). They are referenced with $ref, not rewritten in every operation. An operation is described inside its path, level by level — see the steps below. A parameter is defined by the fields name, in (path, query, header or cookie), required and schema. A path parameter is always required: true. The analyst's endpoint checklist: • purpose — summary and operationId; • parameters with their types, required or not; • the request body (requestBody) with a schema and an example; • all responses, both success and error, not just 200; • the error format; • access requirements (security).
From the root to the response schema
  1. 1
    paths

    the section with all API paths

  2. 2
    resource path

    for example /orders/{orderId}

  3. 3
    method

    get, post, patch…

  4. 4
    responses

    the operation's responses

  5. 5
    status code

    '200', '404'…

  6. 6
    content

    the response body

  7. 7
    media type

    application/json or application/problem+json

  8. 8
    schema

    the body schema, most often a $ref to components

Lesson notes
The contract everything else is built from
OpenAPI is a machine-readable REST API contract in YAML or JSON. One file gives you documentation, stubs (mocks), request validation and client code. The course uses version 3.1: its schemas are JSON Schema 2020-12 from the previous lesson. Version 3.2 (September 2025) is compatible with 3.1 and adds features; just know it exists. Contract-first (API-first): first the contract, agreed by frontend and backend, then the code, and the teams work in parallel. The top level of the document: • openapi — the specification version, for example 3.1.0; • info — the title, description and version of the API itself; • servers — base URLs: https://api.romashka.example/v1; • paths — resource paths and their methods; • components — shared schemas, responses and security schemes (securitySchemes). They are referenced with $ref, not rewritten in every operation. An operation is described inside its path, level by level — see the steps below. A parameter is defined by the fields name, in (path, query, header or cookie), required and schema. A path parameter is always required: true. The analyst's endpoint checklist: • purpose — summary and operationId; • parameters with their types, required or not; • the request body (requestBody) with a schema and an example; • all responses, both success and error, not just 200; • the error format; • access requirements (security).