CyberNotes.it

Sample API specifications

The specifications used in the series. Every one is synthetic — a fictional insurer, invented vehicles, no real data — so they are safe to screen-share, copy into a document, or paste into a tool.

Free to use under CC BY-SA 4.0, like everything else here — share and adapt, including commercially, with attribution and under the same terms. See About for the full statement. If you want a realistic artefact to practise reading, take one.

  • Claims API

    OpenAPI · claims-api.yaml · Part 2 — spec reading

    An OpenAPI 3 contract for a motor-claims service — the worked example the series returns to. Written the way a reasonable specification looks: security schemes declared, errors documented, pagination present.

  • Vehicle Registry API

    OpenAPI · vehicle-registry-api.yaml · Part 2 — data mapping

    An external registry whose conventions deliberately disagree with the Claims API: snake_case fields, lowercase enums, a different date format, API-key auth. The disagreement is the exercise.

  • Vehicle Registry, legacy SOAP

    WSDL · vehicle-registry-legacy.wsdl · Part 1 — integration styles

    The registry's older SOAP interface. Included because analysts still meet WSDL in the wild and reading one should not be a surprise.

  • Claim status event

    Markdown · claim-status-event.md · Part 1 — integration styles

    What an event-driven contract looks like, in contrast to the request/response Claims API — topic, payload, ordering and delivery guarantees.

  • Bordereaux file interface

    Markdown · bordereaux-file-spec.md · Part 1 — integration styles

    A file-based batch contract: layout, schedule, encoding, and what happens when a run is late or partial. The integration style that still carries a great deal of real volume.

  • About these samples

    Markdown · README.md · All parts

    What each file is, how they relate, and the guardrails they were written under. Start here if you are unsure which one you want.

Deliberately flawed — for the gap-hunt exercise

This file is wrong on purpose. A draft written to be wrong. Missing security schemes, missing error responses, no pagination, no rate-limit documentation, and one deliberately ambiguous identifier. Finding the gaps is the exercise — do not use it as a template or cite it as an example.

OpenAPI · mtpl-openapi-v0.yaml · Part 2 — the gap-hunt

Open MTPL draft spec (v0) — the flawed draft

Looking for a specification to learn from? Use the Claims API above, or the live demo API's own documentation. Demo API documentation