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
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
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
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
What an event-driven contract looks like, in contrast to the request/response Claims API — topic, payload, ordering and delivery guarantees.
-
Bordereaux file interface
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
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.
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