API Visualizer

Fields of the resource are explained by its own definition; everything else comes from a specification or a convention, and the badge on each says which.

Keys with a coloured name are explained — open one. What is not explained is this resource’s own data.

• data▸2 items

  1. [0]

     • id▸"1"
     • title▸"What a status code is for"
     • subtitle▸"Semantics, not decoration"
     • body▸"A status code is the one part of a response every intermediary understands."
     • published▸true

  2. [1]

     • id▸"2"
     • title▸"Idempotency in one sentence"
     • body▸"The state after one identical request and after five is the same state."
     • published▸true
• total▸2

Three resources, each reachable at two paths: the collection, and one member of it. They take different verbs because they are different resources that happen to share a prefix — POST to a collection creates a member, and POST to a member means nothing.

On each chip, S marks a safe method — one that changes nothing, so a prefetcher, a crawler, or a browser restoring tabs may perform it unbidden — and I marks an idempotent one, which a proxy or a retry library may repeat after a timeout. POST is the only method that is neither, and every idempotency key ever written exists because of that.

• articles

  Published writing. The resource every verb in this module is demonstrated on.

  /articlescollection

  • GETSIGET /articles. Safe, idempotent. Fetch the current representation of a resource. Safe, so anything may perform it unbidden: a prefetcher, a crawler, a browser restoring tabs, an email client rendering a link preview. A GET that changes state will be triggered by all four.
  • HEADSIHEAD /articles. Safe, idempotent. Identical to GET, but the server sends only the header section. The headers must be the ones GET would have sent -- including Content-Length, describing the body that is deliberately absent. That is how you check a size or an ETag without downloading anything.
  • POSTSIPOST /articles. Not safe, not idempotent. Submit data for the target resource to process however it defines. Neither safe nor idempotent -- the only method that is neither -- so a client that retries after a timeout may create two of something. Everything about idempotency keys exists because of this one row.
  • OPTIONSSIOPTIONS /articles. Safe, idempotent. Ask what the target supports; the answer is the Allow field. Rarely called deliberately. Its common appearance is the CORS preflight, which a browser sends on its own initiative before certain cross-origin requests.
  /articles/1one member

  • GETSIGET /articles/1. Safe, idempotent. Fetch the current representation of a resource. Safe, so anything may perform it unbidden: a prefetcher, a crawler, a browser restoring tabs, an email client rendering a link preview. A GET that changes state will be triggered by all four.
  • HEADSIHEAD /articles/1. Safe, idempotent. Identical to GET, but the server sends only the header section. The headers must be the ones GET would have sent -- including Content-Length, describing the body that is deliberately absent. That is how you check a size or an ETag without downloading anything.
  • PUTSIPUT /articles/1. Not safe, idempotent. Replace the target resource entirely with the enclosed representation. Replace, not merge: a field left out of the body is a field removed. Idempotent because the body is the whole new state, so sending it five times ends where sending it once does.
  • PATCHSIPATCH /articles/1. Not safe, not idempotent. Apply a described set of changes to the target resource. Not idempotent in general, because a patch format may describe a relative change ("add 1 to the count"). JSON Merge Patch happens to be idempotent; JSON Patch need not be. The method cannot promise what the format does not.
  • DELETESIDELETE /articles/1. Not safe, idempotent. Remove the association between the target and its current functionality. Idempotent even though the second call returns 404. Idempotency is about the state left behind, not the status returned: after one delete and after five, the resource is equally gone.
  • OPTIONSSIOPTIONS /articles/1. Safe, idempotent. Ask what the target supports; the answer is the Allow field. Rarely called deliberately. Its common appearance is the CORS preflight, which a browser sends on its own initiative before certain cross-origin requests.
  ▸ 6 fields

• comments

  Replies to articles. Present so the explorer has a second resource to compare against.

  /commentscollection

  • GETSIGET /comments. Safe, idempotent. Fetch the current representation of a resource. Safe, so anything may perform it unbidden: a prefetcher, a crawler, a browser restoring tabs, an email client rendering a link preview. A GET that changes state will be triggered by all four.
  • HEADSIHEAD /comments. Safe, idempotent. Identical to GET, but the server sends only the header section. The headers must be the ones GET would have sent -- including Content-Length, describing the body that is deliberately absent. That is how you check a size or an ETag without downloading anything.
  • POSTSIPOST /comments. Not safe, not idempotent. Submit data for the target resource to process however it defines. Neither safe nor idempotent -- the only method that is neither -- so a client that retries after a timeout may create two of something. Everything about idempotency keys exists because of this one row.
  • OPTIONSSIOPTIONS /comments. Safe, idempotent. Ask what the target supports; the answer is the Allow field. Rarely called deliberately. Its common appearance is the CORS preflight, which a browser sends on its own initiative before certain cross-origin requests.
  /comments/1one member

  • GETSIGET /comments/1. Safe, idempotent. Fetch the current representation of a resource. Safe, so anything may perform it unbidden: a prefetcher, a crawler, a browser restoring tabs, an email client rendering a link preview. A GET that changes state will be triggered by all four.
  • HEADSIHEAD /comments/1. Safe, idempotent. Identical to GET, but the server sends only the header section. The headers must be the ones GET would have sent -- including Content-Length, describing the body that is deliberately absent. That is how you check a size or an ETag without downloading anything.
  • DELETESIDELETE /comments/1. Not safe, idempotent. Remove the association between the target and its current functionality. Idempotent even though the second call returns 404. Idempotency is about the state left behind, not the status returned: after one delete and after five, the resource is equally gone.
  • OPTIONSSIOPTIONS /comments/1. Safe, idempotent. Ask what the target supports; the answer is the Allow field. Rarely called deliberately. Its common appearance is the CORS preflight, which a browser sends on its own initiative before certain cross-origin requests.
  ▸ 4 fields

• reports

  creates asynchronously — 202

  Long-running exports. Creating one is asynchronous, which is why it answers 202 and not 201.

  /reportscollection

  • GETSIGET /reports. Safe, idempotent. Fetch the current representation of a resource. Safe, so anything may perform it unbidden: a prefetcher, a crawler, a browser restoring tabs, an email client rendering a link preview. A GET that changes state will be triggered by all four.
  • HEADSIHEAD /reports. Safe, idempotent. Identical to GET, but the server sends only the header section. The headers must be the ones GET would have sent -- including Content-Length, describing the body that is deliberately absent. That is how you check a size or an ETag without downloading anything.
  • POSTSIPOST /reports. Not safe, not idempotent. Submit data for the target resource to process however it defines. Neither safe nor idempotent -- the only method that is neither -- so a client that retries after a timeout may create two of something. Everything about idempotency keys exists because of this one row.
  • OPTIONSSIOPTIONS /reports. Safe, idempotent. Ask what the target supports; the answer is the Allow field. Rarely called deliberately. Its common appearance is the CORS preflight, which a browser sends on its own initiative before certain cross-origin requests.
  /reports/1one member

  • GETSIGET /reports/1. Safe, idempotent. Fetch the current representation of a resource. Safe, so anything may perform it unbidden: a prefetcher, a crawler, a browser restoring tabs, an email client rendering a link preview. A GET that changes state will be triggered by all four.
  • HEADSIHEAD /reports/1. Safe, idempotent. Identical to GET, but the server sends only the header section. The headers must be the ones GET would have sent -- including Content-Length, describing the body that is deliberately absent. That is how you check a size or an ETag without downloading anything.
  • OPTIONSSIOPTIONS /reports/1. Safe, idempotent. Ask what the target supports; the answer is the Allow field. Rarely called deliberately. Its common appearance is the CORS preflight, which a browser sends on its own initiative before certain cross-origin requests.
  ▸ 3 fields