APIs

How an API is drawn, so a reader takes in what each request does at a glance: in two forms. The compact form shows a whole resource, every request a row; the expanded form takes one request apart, every part named. Drawn the way the diagrams are: the same colours, words as big as the text around them.

2 forms

2 forms

ALLAt a glance

USEHand them to an agent

Paste this into a project's CLAUDE.md or AGENTS.md: it is read at every start, so the agent draws an API this way without being told. The agents' guides hand these over too. To give one form in a conversation, copy it with its Copy for an agent button.

Draw an API the way these forms say:
- Compact: one resource, every request a row: https://raw.githubusercontent.com/vbarbarosh/rules/main/apis/compact.md
- Expanded: one request taken apart: https://raw.githubusercontent.com/vbarbarosh/rules/main/apis/expanded.md

01Compact: one resource, every request a row

A whole resource on one picture: each request a row, in the order they are sent, with what it sends, what it gets back and what the server keeps after it. Which request reads, adds, changes or removes, and what a repeat does, reads down a column.

The articles API: GET the list, GET one, POST, PUT, PATCH and DELETE, each a row with what it sends, its answer, the articles stored after it and what sending it twice does; a red line for an article that is not thereThe articles API: GET the list, GET one, POST, PUT, PATCH and DELETE, each a row with what it sends, its answer, the articles stored after it and what sending it twice does; a red line for an article that is not there

Fits when

  • A resource and its requests: list, read, add, replace, change, remove; the reader learns the API, or checks what it does.
  • The difference between requests matters: PUT beside PATCH, POST beside PUT, what a repeat does.
  • The state after each request says more than its answer: what is added, replaced, gone.

Not when

  • One request in detail, its headers and body, an error's answer: the expanded form.
  • The order of calls between parts, a server, a database, a queue: a sequence diagram.
  • Many resources at once: a compact picture each, or a matrix of addresses by methods.

How it is drawn

  1. A row per request, in the order they are sent, on a card of its own: the method as a badge, the address in a monospace font.
  2. The method's colour says what it does to the data: blue reads, green adds, orange changes, red removes. A legend under the picture says so.
  3. Five columns: the request; what it sends (a body in a code box, else "nothing"); what it gets back (the status in green, a line on the body); what is stored after it (each record a chip, the one touched in the method's colour, a removed one faded in a dashed red box); sent twice ("same", or what changes more in orange).
  4. One small example of data runs through every row (articles #1 and #2, then #3 added, changed and removed), so each row's change shows.
  5. What fails goes in a red line under the rows: a record that is not there, fields that are wrong, with their statuses.
  6. Around it: a title with the resource, one line of how to read it.
In the author's words
  • Make a visual picture of some REST API, a standard one, articles for example: create, delete, then full replace, PUT, and PATCH, a partial update. Show this API at a glance. (2026-10-17 23:47)
  • This one and One request, taken apart: they are compact and expanded forms. Let's add them to a new page, APIs. (2026-10-18 00:56)
compact.md

02Expanded: one request taken apart

One request and its answer, every part named: the method and address, the headers, the body, the status. Each part sits in a code box as it is sent, its name and what it is for beside it, so a reader learns what a request is made of and what to look at in one.

A PATCH to article 3 and its 200 answer: method and address, headers, a body with only the title, then the status, headers and the whole article as it is now, each part named on the sideA PATCH to article 3 and its 200 answer: method and address, headers, a body with only the title, then the status, headers and the whole article as it is now, each part named on the side

Fits when

  • One request matters in detail: the one a bug is in, the one a client has to build, the one the docs explain first.
  • The answer has to be read: what the status says, what the body holds, how an error names the field that is wrong.
  • A newcomer learns the shape of a request once, to read the compact form after it.

Not when

  • The whole resource, all its requests side by side: the compact form.
  • Parts talking to each other, in time order: a sequence diagram.
  • The difference is one field: the request and the answer as text, the field marked, say it better.

How it is drawn

  1. Two code boxes, the request on top and the answer under it, each in its parts as they are sent: the first line, the headers, the body. A dashed line between the parts.
  2. The name of each part beside it, on a coloured bar: the method's colour on the method and address, green on a status that worked and red on one that failed, blue on a body, grey on headers. Under the name, a few words on what it is for in this request.
  3. Real values, short: a token cut with "…", a body with only the fields that matter.
  4. A failure is drawn the same way, the status and the body that names what is wrong in red, so the reader sees what a client gets back.
  5. Around it: a title with what the request does, one line of what it shows.
A POST with no title and its 422 answer: the status and an errors body naming the title as required, both in redA POST with no title and its 422 answer: the status and an errors body naming the title as required, both in red
In the author's words
  • One request, taken apart: this is a good one. It and the compact table are compact and expanded forms. Let's add them to a new page, APIs. (2026-10-18 00:56)
expanded.md