Проектирование API: ресурсы, версии, ошибки, пагинация

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Request validation failed",
  "errors": [
    {
      "pointer": "#/service",
      "detail": "must have required property 'service'"
    },
    {
      "pointer": "#/starts_at",
      "detail": "must match format \"date-time\""
    }
  ]
}

API=http://localhost:3917/v1
AUTH="Authorization: Bearer demo-token"
JSON="Content-Type: application/json"
KEY='Idempotency-Key: "8e03978e-40d5-43e8-bc93-6894a57f9324"'
BODY='{"master_id":"m-1","service":"haircut","starts_at":"2026-11-02T10:00:00+05:00"}'

# 1. Create, then retry with the same key: the same booking comes back
curl -si -w '\n' -X POST $API/bookings -H "$AUTH" -H "$KEY" -H "$JSON" -d "$BODY"
curl -s -w '\n' -X POST $API/bookings -H "$AUTH" -H "$KEY" -H "$JSON" -d "$BODY"

# 2. Same key, different body: 422
curl -s -w '\n' -X POST $API/bookings -H "$AUTH" -H "$KEY" -H "$JSON" \
  -d '{"master_id":"m-1","service":"coloring","starts_at":"2026-11-02T10:00:00+05:00"}'

# 3. Invalid body: 400 with a pointer per field
curl -s -w '\n' -X POST $API/bookings -H "$AUTH" -H "$JSON" \
  -H 'Idempotency-Key: "0b5f1c2e-7d1a-4c11-9e55-3f0c2a9d7b10"' \
  -d '{"master_id":"m-1","starts_at":"tomorrow"}'

$ bash demo.sh
HTTP/1.1 201 Created
Location: /v1/bookings/9ff0c277-6654-4fd6-8282-75f1156b6564
ETag: "v1"
Content-Type: application/json; charset=utf-8
Content-Length: 183

{"id":"9ff0c277-6654-4fd6-8282-75f1156b6564","master_id":"m-1","service":"haircut","starts_at":"2026-11-02T05:00:00.000Z","status":"confirmed","created_at":"2026-10-12T02:25:52.357Z"}
{"id":"9ff0c277-6654-4fd6-8282-75f1156b6564","master_id":"m-1","service":"haircut","starts_at":"2026-11-02T05:00:00.000Z","status":"confirmed","created_at":"2026-10-12T02:25:52.357Z"}
{"type":"https://api.salon.test/problems/idempotency-key-reused","title":"Idempotency-Key is already used","status":422,"detail":"This key was already used with a different request body"}
{"type":"about:blank","title":"Bad Request","status":400,"detail":"Request validation failed","errors":[{"pointer":"#/service","detail":"must have required property 'service'"},{"pointer":"#/starts_at","detail":"must match format \"date-time\""}]}

Deprecation: @1688169599
Link: <https://developer.example.com/deprecation>;
      rel="deprecation"; type="text/html"
Sunset: Sun, 30 Jun 2024 23:59:59 UTC

{
  "name": "bookings-api",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "node src/server.js",
    "test": "node --test",
    "lint:api": "redocly lint openapi.yaml"
  },
  "dependencies": {
    "ajv": "^8.20.0",
    "ajv-formats": "^3.0.1",
    "express": "^5.3.0",
    "yaml": "^2.9.1"
  },
  "devDependencies": {
    "@redocly/cli": "^2.62.1",
    "supertest": "^7.3.1"
  }
}

openapi: 3.1.2
info:
  title: Bookings API
  version: 1.0.0
  summary: Client bookings for a salon.
  description: |
    Errors use Problem Details (RFC 9457, application/problem+json).
    Clients must ignore unknown response fields: new optional fields
    are added without a new major version.
  license:
    name: MIT
    identifier: MIT
servers:
  - url: https://api.salon.test/v1
security:
  - bearerAuth: []
tags:
  - name: bookings
    description: Client bookings
paths:
  /bookings:
    get:
      tags: [bookings]
      operationId: listBookings
      summary: List bookings (cursor pagination)
      parameters:
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
        - name: cursor
          in: query
          description: Opaque value of next_cursor from the previous page.
          schema: { type: string }
        - name: status
          in: query
          schema: { $ref: '#/components/schemas/BookingStatus' }
        - name: master_id
          in: query
          schema: { type: string }
        - name: sort
          in: query
          description: Sort field; a leading minus means descending.
          schema: { type: string, enum: [starts_at, -starts_at], default: starts_at }
      responses:
        '200':
          description: One page of bookings.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BookingPage' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      tags: [bookings]
      operationId: createBooking
      summary: Create a booking
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: |
            Quoted unique string, e.g. "8e03978e-40d5-43e8-bc93-6894a57f9324".
            A retry with the same key and body returns the stored result.
          schema: { type: string, pattern: '^"[A-Za-z0-9-]{16,64}"$' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BookingCreate' }
      responses:
        '201':
          description: Booking created.
          headers:
            Location:
              description: URL of the new booking.
              schema: { type: string, format: uri-reference }
            ETag: { $ref: '#/components/headers/ETag' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Booking' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/UnprocessableContent' }
  /bookings/{bookingId}:
    parameters:
      - name: bookingId
        in: path
        required: true
        schema: { type: string, format: uuid }
    get:
      tags: [bookings]
      operationId: getBooking
      summary: Get a booking
      responses:
        '200':
          description: The booking.
          headers:
            ETag: { $ref: '#/components/headers/ETag' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Booking' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    patch:
      tags: [bookings]
      operationId: updateBooking
      summary: Reschedule, cancel or annotate a booking (JSON Merge Patch)
      parameters:
        - name: If-Match
          in: header
          required: true
          description: ETag from the last GET; protects against lost updates.
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema: { $ref: '#/components/schemas/BookingPatch' }
      responses:
        '200':
          description: Updated booking.
          headers:
            ETag: { $ref: '#/components/headers/ETag' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Booking' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '412': { $ref: '#/components/responses/PreconditionFailed' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '428': { $ref: '#/components/responses/PreconditionRequired' }
components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer }
  headers:
    ETag:
      description: Version of the booking; send it back in If-Match.
      schema: { type: string }
  schemas:
    BookingStatus:
      type: string
      enum: [confirmed, cancelled]
    Booking:
      type: object
      required: [id, master_id, service, starts_at, status, created_at]
      properties:
        id: { type: string, format: uuid }
        master_id: { type: string }
        service: { type: string }
        starts_at: { type: string, format: date-time }
        status: { $ref: '#/components/schemas/BookingStatus' }
        note: { type: string, maxLength: 500 }
        created_at: { type: string, format: date-time }
    BookingCreate:
      type: object
      additionalProperties: false
      required: [master_id, service, starts_at]
      properties:
        master_id: { type: string, minLength: 1 }
        service: { type: string, minLength: 1 }
        starts_at: { type: string, format: date-time }
        note: { type: string, maxLength: 500 }
    BookingPatch:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        starts_at: { type: string, format: date-time }
        status: { const: cancelled }
        note:
          type: [string, 'null']
          maxLength: 500
          description: null removes the note (RFC 7396).
    BookingPage:
      type: object
      required: [data, next_cursor]
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/Booking' }
        next_cursor:
          type: [string, 'null']
          description: Pass as ?cursor= to get the next page; null on the last page.
    Problem:
      type: object
      required: [type, title, status]
      properties:
        type: { type: string, format: uri-reference }
        title: { type: string }
        status: { type: integer, minimum: 400, maximum: 599 }
        detail: { type: string }
        instance: { type: string, format: uri-reference }
        errors:
          type: array
          description: Extension member — one item per invalid field or parameter.
          items:
            type: object
            required: [detail]
            properties:
              detail: { type: string }
              pointer: { type: string, description: JSON Pointer into the request body. }
              parameter: { type: string, description: Name of the invalid query parameter. }
  responses:
    BadRequest:
      description: Malformed request or failed validation.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
    Unauthorized:
      description: Missing or invalid bearer token.
      headers:
        WWW-Authenticate:
          description: Authentication scheme the client must use.
          schema: { type: string }
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
    NotFound:
      description: No booking with this id.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
    Conflict:
      description: The slot is already taken.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
    PreconditionFailed:
      description: If-Match does not match the current ETag; re-read the booking.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
    PreconditionRequired:
      description: The If-Match header is required.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
    UnprocessableContent:
      description: Idempotency-Key was already used with a different body.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
    UnsupportedMediaType:
      description: PATCH body must be application/merge-patch+json.
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }

$ npm run lint:api
> bookings-api@1.0.0 lint:api
> redocly lint openapi.yaml

No configurations were provided -- using built in recommended configuration by default.

validating openapi.yaml...
openapi.yaml: validated in 23ms

Woohoo! Your API description is valid. 🎉

$ npx redocly lint openapi.yaml --format=stylish
No configurations were provided -- using built in recommended configuration by default.

validating openapi.yaml...
openapi.yaml:
  49:23  error    no-unresolved-refs    Can't resolve $ref
  176:5  warning  no-unused-components  Component: "BookingPage" is never used.

openapi.yaml: validated in 24ms

❌ Validation failed with 1 error and 1 warning.
run `redocly lint --generate-ignore-file` to add all problems to the ignore file.
$ echo $?
1

import { readFileSync } from "node:fs";
import { Ajv2020 } from "ajv/dist/2020.js";
import addFormats from "ajv-formats";
import { parse } from "yaml";

const doc = parse(readFileSync(new URL("../openapi.yaml", import.meta.url), "utf8"));

// OpenAPI 3.1 schemas are JSON Schema 2020-12, so one validator serves
// both the server (requests) and the tests (responses).
const ajv = new Ajv2020({ allErrors: true, strict: false });
addFormats(ajv);
ajv.addSchema({ $id: "openapi", components: doc.components });

export function schemaErrors(name, data) {
  const validate = ajv.getSchema(`openapi#/components/schemas/${name}`);
  if (validate(data)) return [];
  return validate.errors.map((e) => {
    const missing = e.params.missingProperty ? `/${e.params.missingProperty}` : "";
    const extra = e.params.additionalProperty ? `/${e.params.additionalProperty}` : "";
    return { pointer: `#${e.instancePath}${missing}${extra}`, detail: e.message };
  });
}

import express from "express";
import { createHash, randomUUID } from "node:crypto";
import { STATUS_CODES } from "node:http";
import { schemaErrors } from "./contract.js";

const TYPES = "https://api.salon.test/problems/";

class Problem extends Error {
  constructor(status, detail, { type, title, headers, ...extra } = {}) {
    super(detail);
    this.status = status;
    this.headers = headers ?? {};
    this.body = {
      type: type ? TYPES + type : "about:blank",
      title: title ?? STATUS_CODES[status],
      status,
      detail,
      ...extra,
    };
  }
}

const etag = (b) => `"v${b.version}"`;
const view = ({ version, ...booking }) => booking;
const encodeCursor = (b, sort) =>
  Buffer.from(JSON.stringify([sort, b.starts_at, b.id])).toString("base64url");

function decodeCursor(cursor, sort) {
  try {
    const [s, startsAt, id] = JSON.parse(Buffer.from(cursor, "base64url").toString());
    if (s === sort && typeof startsAt === "string" && typeof id === "string") return { startsAt, id };
  } catch {}
  throw new Problem(400, "Cursor is invalid or belongs to another sort order", {
    errors: [{ parameter: "cursor", detail: "use next_cursor from the previous page" }],
  });
}

export function createApp() {
  const app = express();
  app.disable("x-powered-by");
  app.set("etag", false); // ETag is the booking version, set explicitly below
  const bookings = new Map();
  const idempotency = new Map();

  const slotTaken = (masterId, startsAt, exceptId) =>
    [...bookings.values()].some(
      (b) => b.id !== exceptId && b.status === "confirmed" &&
        b.master_id === masterId && b.starts_at === startsAt,
    );

  app.use(express.json({ type: ["application/json", "application/merge-patch+json"] }));

  // Stub authentication: a real API verifies the token (see the auth lessons).
  app.use((req, res, next) => {
    const token = /^Bearer (\S+)$/.exec(req.get("authorization") ?? "")?.[1];
    if (!token) {
      throw new Problem(401, "Send a bearer token", { headers: { "WWW-Authenticate": "Bearer" } });
    }
    req.account = token;
    next();
  });

  const v1 = express.Router();

  v1.get("/bookings", (req, res) => {
    const { limit = "20", cursor, status, master_id, sort = "starts_at" } = req.query;
    const size = Number(limit);
    const errors = [];
    if (!Number.isInteger(size) || size < 1 || size > 100) {
      errors.push({ parameter: "limit", detail: "must be an integer from 1 to 100" });
    }
    if (!["starts_at", "-starts_at"].includes(sort)) {
      errors.push({ parameter: "sort", detail: "must be starts_at or -starts_at" });
    }
    if (status !== undefined && !["confirmed", "cancelled"].includes(status)) {
      errors.push({ parameter: "status", detail: "must be confirmed or cancelled" });
    }
    if (errors.length) throw new Problem(400, "Query validation failed", { errors });

    const dir = sort === "-starts_at" ? -1 : 1;
    const cmp = (a, b) => dir * (a.starts_at.localeCompare(b.starts_at) || a.id.localeCompare(b.id));
    let rows = [...bookings.values()]
      .filter((b) => (!status || b.status === status) && (!master_id || b.master_id === master_id))
      .sort(cmp);
    if (cursor) {
      const after = decodeCursor(cursor, sort);
      rows = rows.filter((b) => cmp(b, { starts_at: after.startsAt, id: after.id }) > 0);
    }
    const page = rows.slice(0, size);
    const hasMore = rows.length > size;
    res.json({
      data: page.map(view),
      next_cursor: hasMore ? encodeCursor(page.at(-1), sort) : null,
    });
  });

  v1.post("/bookings", (req, res) => {
    const key = req.get("idempotency-key");
    if (!key) {
      throw new Problem(400, "This operation requires an Idempotency-Key header", {
        type: "idempotency-key-missing", title: "Idempotency-Key is missing",
      });
    }
    if (!/^"[A-Za-z0-9-]{16,64}"$/.test(key)) {
      throw new Problem(400, "Idempotency-Key must be a quoted string of 16-64 letters, digits or dashes", {
        type: "idempotency-key-invalid", title: "Idempotency-Key is invalid",
      });
    }
    const errors = schemaErrors("BookingCreate", req.body);
    if (errors.length) throw new Problem(400, "Request validation failed", { errors });

    // The key is scoped to the account: one client cannot replay another's result.
    const scope = `${req.account}:${key}`;
    const fingerprint = createHash("sha256").update(JSON.stringify(req.body)).digest("hex");
    const saved = idempotency.get(scope);
    if (saved) {
      if (saved.fingerprint !== fingerprint) {
        throw new Problem(422, "This key was already used with a different request body", {
          type: "idempotency-key-reused", title: "Idempotency-Key is already used",
        });
      }
      return res.status(201).set(saved.headers).json(saved.body);
    }

    const startsAt = new Date(req.body.starts_at).toISOString();
    if (slotTaken(req.body.master_id, startsAt)) {
      throw new Problem(409, "The master already has a booking at this time", {
        type: "slot-taken", title: "Slot is already taken",
      });
    }
    const booking = {
      id: randomUUID(),
      master_id: req.body.master_id,
      service: req.body.service,
      starts_at: startsAt,
      status: "confirmed",
      ...(req.body.note !== undefined && { note: req.body.note }),
      created_at: new Date().toISOString(),
      version: 1,
    };
    bookings.set(booking.id, booking);
    const headers = { Location: `/v1/bookings/${booking.id}`, ETag: etag(booking) };
    idempotency.set(scope, { fingerprint, headers, body: view(booking) });
    res.status(201).set(headers).json(view(booking));
  });

  const find = (id) => {
    const booking = bookings.get(id);
    if (!booking) throw new Problem(404, `Booking ${id} not found`);
    return booking;
  };

  v1.get("/bookings/:id", (req, res) => {
    const booking = find(req.params.id);
    res.set("ETag", etag(booking)).json(view(booking));
  });

  v1.patch("/bookings/:id", (req, res) => {
    if (!req.is("application/merge-patch+json")) {
      throw new Problem(415, "Use Content-Type: application/merge-patch+json");
    }
    const booking = find(req.params.id);
    const ifMatch = req.get("if-match");
    if (!ifMatch) throw new Problem(428, "Send If-Match with the ETag from your last GET");
    if (ifMatch !== etag(booking)) {
      throw new Problem(412, "The booking has changed since you read it; GET it again");
    }
    const errors = schemaErrors("BookingPatch", req.body);
    if (errors.length) throw new Problem(400, "Request validation failed", { errors });

    const next = { ...booking };
    if ("starts_at" in req.body) next.starts_at = new Date(req.body.starts_at).toISOString();
    if ("status" in req.body) next.status = req.body.status;
    if (req.body.note === null) delete next.note; // RFC 7396: null removes the member
    else if ("note" in req.body) next.note = req.body.note;
    if (next.status === "confirmed" && slotTaken(next.master_id, next.starts_at, next.id)) {
      throw new Problem(409, "The master already has a booking at this time", {
        type: "slot-taken", title: "Slot is already taken",
      });
    }
    next.version += 1;
    bookings.set(next.id, next);
    res.set("ETag", etag(next)).json(view(next));
  });

  app.use("/v1", v1);

  app.use((req, res, next) => {
    next(new Problem(404, `Route ${req.method} ${req.path} not found`));
  });

  app.use((err, req, res, next) => {
    if (res.headersSent) return next(err);
    const problem =
      err instanceof Problem ? err
      : err.type === "entity.parse.failed" ? new Problem(400, "Request body is not valid JSON")
      : null;
    if (!problem) {
      console.error(err);
      return res.status(500).type("application/problem+json")
        .json(new Problem(500, "Unexpected server error").body);
    }
    res.status(problem.status).set(problem.headers)
      .type("application/problem+json").json(problem.body);
  });

  return app;
}

import { createApp } from "./app.js";

const port = Number(process.env.PORT ?? 3000);
createApp().listen(port, () => console.log(`Bookings API stub on http://localhost:${port}/v1`));

import { test } from "node:test";
import assert from "node:assert/strict";
import { randomUUID } from "node:crypto";
import request from "supertest";
import { createApp } from "../src/app.js";
import { schemaErrors } from "../src/contract.js";

const AUTH = { Authorization: "Bearer test-account" };
const key = () => `"${randomUUID()}"`;
const slot = (h) => `2026-11-02T${String(h).padStart(2, "0")}:00:00.000Z`;
const draft = (h = 10) => ({ master_id: "m-1", service: "haircut", starts_at: slot(h) });

// Contract check: the body matches the schema from openapi.yaml.
function matches(name, body) {
  assert.deepEqual(schemaErrors(name, body), [], `${name}: ${JSON.stringify(body)}`);
}

function isProblem(res, status) {
  assert.equal(res.status, status);
  assert.match(res.headers["content-type"], /^application\/problem\+json/);
  assert.equal(res.body.status, status);
  matches("Problem", res.body);
}

test("POST creates a booking: 201, Location, ETag, body matches the contract", async () => {
  const res = await request(createApp()).post("/v1/bookings")
    .set(AUTH).set("Idempotency-Key", key()).send(draft());
  assert.equal(res.status, 201);
  assert.equal(res.headers.location, `/v1/bookings/${res.body.id}`);
  assert.equal(res.headers.etag, '"v1"');
  matches("Booking", res.body);
});

test("retry with the same key and body returns the same booking, no duplicate", async () => {
  const app = createApp();
  const k = key();
  const first = await request(app).post("/v1/bookings").set(AUTH).set("Idempotency-Key", k).send(draft());
  const retry = await request(app).post("/v1/bookings").set(AUTH).set("Idempotency-Key", k).send(draft());
  assert.equal(retry.status, 201);
  assert.equal(retry.body.id, first.body.id);
  const list = await request(app).get("/v1/bookings").set(AUTH);
  assert.equal(list.body.data.length, 1);
});

test("same key with another body is 422, missing key is 400", async () => {
  const app = createApp();
  const k = key();
  await request(app).post("/v1/bookings").set(AUTH).set("Idempotency-Key", k).send(draft(10));
  isProblem(await request(app).post("/v1/bookings").set(AUTH).set("Idempotency-Key", k).send(draft(11)), 422);
  isProblem(await request(app).post("/v1/bookings").set(AUTH).send(draft(12)), 400);
});

test("invalid body is 400 with pointers; taken slot is 409", async () => {
  const app = createApp();
  const bad = await request(app).post("/v1/bookings").set(AUTH).set("Idempotency-Key", key())
    .send({ master_id: "m-1", starts_at: "tomorrow", price: 0 });
  isProblem(bad, 400);
  const pointers = bad.body.errors.map((e) => e.pointer).sort();
  assert.deepEqual(pointers, ["#/price", "#/service", "#/starts_at"]);

  await request(app).post("/v1/bookings").set(AUTH).set("Idempotency-Key", key()).send(draft(10));
  isProblem(await request(app).post("/v1/bookings").set(AUTH).set("Idempotency-Key", key()).send(draft(10)), 409);
});

test("cursor pagination walks every booking exactly once", async () => {
  const app = createApp();
  for (const h of [13, 9, 11, 10, 12]) {
    await request(app).post("/v1/bookings").set(AUTH).set("Idempotency-Key", key()).send(draft(h));
  }
  const seen = [];
  let cursor = null;
  do {
    const res = await request(app).get("/v1/bookings")
      .query({ limit: 2, sort: "-starts_at", ...(cursor && { cursor }) }).set(AUTH);
    assert.equal(res.status, 200);
    matches("BookingPage", res.body);
    seen.push(...res.body.data.map((b) => b.starts_at));
    cursor = res.body.next_cursor;
  } while (cursor);
  assert.deepEqual(seen, [13, 12, 11, 10, 9].map(slot));

  isProblem(await request(app).get("/v1/bookings").query({ limit: 500 }).set(AUTH), 400);
  isProblem(await request(app).get("/v1/bookings").query({ cursor: "garbage" }).set(AUTH), 400);
});

test("PATCH needs If-Match: 428 without it, 412 when stale, 200 when current", async () => {
  const app = createApp();
  const created = await request(app).post("/v1/bookings").set(AUTH).set("Idempotency-Key", key()).send(draft());
  const url = created.headers.location;
  const patch = (body, ifMatch) => {
    const req = request(app).patch(url).set(AUTH).set("Content-Type", "application/merge-patch+json");
    return (ifMatch ? req.set("If-Match", ifMatch) : req).send(JSON.stringify(body));
  };

  isProblem(await patch({ note: "window seat" }), 428);
  const ok = await patch({ note: "window seat" }, created.headers.etag);
  assert.equal(ok.status, 200);
  assert.equal(ok.body.note, "window seat");
  assert.equal(ok.headers.etag, '"v2"');
  isProblem(await patch({ status: "cancelled" }, created.headers.etag), 412);

  const cleared = await patch({ note: null }, ok.headers.etag);
  assert.equal("note" in cleared.body, false);
  matches("Booking", cleared.body);
});

test("unknown booking is 404, request without a token is 401", async () => {
  const app = createApp();
  isProblem(await request(app).get(`/v1/bookings/${randomUUID()}`).set(AUTH), 404);
  const anon = await request(app).get("/v1/bookings");
  isProblem(anon, 401);
  assert.equal(anon.headers["www-authenticate"], "Bearer");
});

$ npm test
> bookings-api@1.0.0 test
> node --test

✔ POST creates a booking: 201, Location, ETag, body matches the contract (31.7978ms)
✔ retry with the same key and body returns the same booking, no duplicate (7.2981ms)
✔ same key with another body is 422, missing key is 400 (9.4061ms)
✔ invalid body is 400 with pointers; taken slot is 409 (5.7477ms)
✔ cursor pagination walks every booking exactly once (21.0143ms)
✔ PATCH needs If-Match: 428 without it, 412 when stale, 200 when current (7.9507ms)
✔ unknown booking is 404, request without a token is 401 (2.9521ms)
ℹ tests 7
ℹ suites 0
ℹ pass 7
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 374.3534

API=http://localhost:3917/v1
AUTH="Authorization: Bearer demo-token"
PATCH="Content-Type: application/merge-patch+json"
URL=$API/bookings/$1

# Without If-Match: 428
curl -s -w '\n' -X PATCH $URL -H "$AUTH" -H "$PATCH" -d '{"note":"first visit"}'
# With the current ETag: 200 and a new ETag
curl -si -w '\n' -X PATCH $URL -H "$AUTH" -H "$PATCH" -H 'If-Match: "v1"' -d '{"note":"first visit"}'
# The same stale ETag again: 412
curl -s -w '\n' -X PATCH $URL -H "$AUTH" -H "$PATCH" -H 'If-Match: "v1"' -d '{"status":"cancelled"}'

$ bash demo-patch.sh 9ff0c277-6654-4fd6-8282-75f1156b6564
{"type":"about:blank","title":"Precondition Required","status":428,"detail":"Send If-Match with the ETag from your last GET"}
HTTP/1.1 200 OK
ETag: "v2"
Content-Type: application/json; charset=utf-8
Content-Length: 204

{"id":"9ff0c277-6654-4fd6-8282-75f1156b6564","master_id":"m-1","service":"haircut","starts_at":"2026-11-02T05:00:00.000Z","status":"confirmed","created_at":"2026-10-12T02:25:52.357Z","note":"first visit"}
{"type":"about:blank","title":"Precondition Failed","status":412,"detail":"The booking has changed since you read it; GET it again"}