CRUD contract template

Copy the block below into an openapi.yaml and replace the <placeholders>.

openapi: 3.1.0

info:
  title: Orders API
  version: 1.0.0
  description: Read and write the orders belonging to the authenticated customer.

servers:
  - url: https://api.example.com

tags:
  - name: orders
    description: Customer orders

paths:
  /orders:
    get:
      operationId: listOrders
      tags: [orders]
      summary: List the customer's orders
      parameters:
        - name: page
          in: query
          required: false
          schema: { type: integer, minimum: 1, default: 1 }
        - name: page_size
          in: query
          required: false
          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
        - name: status
          in: query
          required: false
          schema: { type: string, enum: [new, paid, shipped, cancelled] }
      responses:
        '200':
          description: A page of orders
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderList' }
        '401':
          $ref: '#/components/responses/Unauthenticated'

    post:
      operationId: createOrder
      tags: [orders]
      summary: Create an order
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateOrder' }
      responses:
        '201':
          description: The created order
          headers:
            Location:
              description: The URL of the created order
              schema: { type: string, format: uri }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Order' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthenticated'

  /orders/{orderId}:
    parameters:
      - name: orderId
        in: path
        required: true
        schema: { type: string, pattern: '^A-[0-9]+$' }
    get:
      operationId: getOrder
      tags: [orders]
      summary: Fetch a single order
      responses:
        '200':
          description: The order
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Order' }
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/AccessDenied'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateOrder
      tags: [orders]
      summary: Update an order
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UpdateOrder' }
      responses:
        '200':
          description: The updated order
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Order' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/AccessDenied'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Unprocessable'

components:
  schemas:
    CreateOrder:
      type: object
      additionalProperties: false
      required: [items]
      properties:
        items:
          type: array
          minItems: 1
          maxItems: 100
          items:
            type: object
            additionalProperties: false
            required: [sku, quantity]
            properties:
              sku: { type: string, pattern: '^[A-Z]{3}-[0-9]{4}$' }
              quantity: { type: integer, minimum: 1, maximum: 999 }

    UpdateOrder:
      type: object
      additionalProperties: false
      properties:
        status:
          type: string
          enum: [new, paid, shipped, cancelled]

    Order:
      type: object
      additionalProperties: false
      required: [id, status, total, currency, createdAt]
      properties:
        id: { type: string, pattern: '^A-[0-9]+$' }
        status: { type: string, enum: [new, paid, shipped, cancelled] }
        total: { type: number, format: decimal, minimum: 0 }
        currency: { type: string, enum: [EUR, USD, GBP] }
        createdAt: { type: string, format: date-time }
        items:
          type: array
          items:
            type: object
            additionalProperties: false
            required: [sku, quantity]
            properties:
              sku: { type: string, pattern: '^[A-Z]{3}-[0-9]{4}$' }
              quantity: { type: integer, minimum: 1 }

    OrderList:
      type: object
      additionalProperties: false
      required: [items, total, page, pageSize]
      properties:
        items:
          type: array
          items: { $ref: '#/components/schemas/Order' }
        total: { type: integer, minimum: 0 }
        page: { type: integer, minimum: 1 }
        pageSize: { type: integer, minimum: 1, maximum: 100 }

    Error:
      type: object
      additionalProperties: false
      required: [code, message]
      properties:
        code: { type: string }
        message: { type: string }

  responses:
    BadRequest:
      description: The request body is malformed
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
          example: { code: "MALFORMED_BODY", message: "Request body is not valid JSON." }
    Unauthenticated:
      description: No valid credentials were supplied
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
          example: { code: "AUTHENTICATION_REQUIRED", message: "A valid access token is required." }
    AccessDenied:
      description: The order does not belong to the authenticated customer
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
          example: { code: "ORDER_ACCESS_DENIED", message: "This order does not belong to you." }
    NotFound:
      description: No such order
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
          example: { code: "ORDER_NOT_FOUND", message: "No order exists with that identifier." }
    Unprocessable:
      description: The request is well-formed but cannot be processed
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
          example: { code: "ORDER_STATE_INVALID", message: "This order can no longer be changed." }

Why it is shaped this way

operationId on every operation. It is the join key between the contract and the behaviour. Without it, a scenario cannot reference an operation, and the cross-format consistency check has nothing to check.

additionalProperties: false on every schema. Without it, a service that starts sending a new field passes validation while a strict consumer breaks. Turn it on unless you genuinely want an open schema.

Every error response has a schema and an example. The example is validated against the schema during the build, which catches the copies that were never updated. And the literal error codes in the examples are what the Gherkin scenarios assert against.

The 403 and the 404 are separate responses. They mean different things and leak different information. Deciding to conflate them is a legitimate choice — but it should be written down as one, not arrived at by accident.

Constraints are structural, not prose. minimum, maximum, pattern, enum, minItems are all executable checks. A comment saying "must be a positive amount" is not.

422 is distinguished from 400. 400 is a malformed request; 422 is a well-formed request that cannot be processed. Splitting them means a client can tell "fix your JSON" from "you cannot do that right now".

Parameters are constrained at the boundary. page_size has maximum: 100, and the behaviour template has a scenario asserting that a larger value is refused with PAGE_SIZE_TOO_LARGE. The constraint and the behaviour are specified in their respective halves, and the consistency check verifies they agree.

Pair it with a behaviour file

This contract is shapes. The behaviour — when an order may be changed, what cancelling one does to a payment, which transitions are legal — belongs in a Gherkin feature file. See the REST API behaviour template.

Next