Requirements to API: verbs, numbers, calls

• Write 3 to 5 verbs. Agree on them before you draw a box.
• Write one line of what is out of scope.
• Turn each adjective into a number. The next panel shows how.

These four verbs are the functional scope. For each quality, I want a number we can test.

SLI: what you measure (the share of good requests). SLO: the target for it. Measure at the load balancer, where users see the result.

By available I mean 99.9% of requests succeed over 30 days. That is a budget of about 43 minutes.

Three parts in a row at 99.9% give only 99.7%. Two copies of each part bring the path back above 99.9%.

downtime(target, period) = (1 - target) × period1
  // 99.9% over 30 days: 0.001 × 2,592,000 s = 2,592 s = 43.2 min

redundant(a, copies) = 1 - (1 - a)^copies   // down only if every copy is down2
chain(a, parts)      = a^parts               // up only if every part is up3

  // 3 parts in a row at 99.9%:  0.999^3        = 99.7%4
  // 2 copies of each part:      (1 - 0.001^2)^3 = 99.9997%5

// Downtime is the time a service may be down in a period and still meet the target.
func Downtime(availability, periodSeconds float64) float64 {
  return (1 - availability) * periodSeconds
}

// Redundant is the availability of n copies when any one copy is enough and copies fail
// independently: the service is down only when every copy is down.
func Redundant(availability float64, n int) float64 {
  return 1 - math.Pow(1-availability, float64(n))
}

// Chain is the availability of components that a request needs one after another: the request
// succeeds only when every component is up.
func Chain(availability float64, n int) float64 {
  return math.Pow(availability, float64(n))
}

Downtime is one minus the target, times the period. Parts in a row multiply; copies in parallel multiply their failures.

• Use plural nouns for collections and an opaque id for each item.
• Put the version in the path (/v1) or a header, and never break a published field.
• Return the created resource and its Location, so the client needs no second read.

Paths are nouns and methods are verbs. Every call that creates or pays is safe to retry.

Codes as the IETF HTTP API working group draft for the Idempotency-Key header suggests.

The client makes one key per user action and sends it on every retry. The server stores the key with the result in the same transaction.

Postgres computes and discards the rows an OFFSET skips (PostgreSQL documentation, LIMIT and OFFSET).

I use a cursor: the last key the client saw. Inserts do not shift it, and each page is an index seek.

A 4xx means the client must change the request. A 5xx or 429 can be retried with the same key, after a wait.

• Async work goes through a durable queue, so a crash does not lose it.
• Write the job in the same transaction as the data (an outbox), so neither is lost alone.
• 202 returns a status URL. The client polls it, or a webhook calls back.

The guest waits for the booking, so confirm is synchronous. The email and the search index update go through a queue.

Each verb is a call, each call reaches one store, and each number lands on the component that meets it.

Search can be stale, the hold is fast and can be lost, and the confirm transaction decides. The list reads the guest's own bookings by key.