Life of a call · StartupBuilder

Harbor Residential's property software renews a lease through Leaseline's API. One call passes six checks in a fixed order, records one Action, and sends one Event to every receiver that asked for it.

The call

Leaseline declares a Lease Noun with a Lease.renew Verb. Harbor Residential's sync calls it with its own key:

Terminal

curl -X POST https://api.leaseline.app/leases/lease_4loEed1JG4/renew \
  -H "Authorization: Bearer $LEASELINE_API_KEY" \
  -H "Idempotency-Key: harbor-renewal-5c" \
  -H "Content-Type: application/json" \
  -d '{"months":12}'

JSON

{
  "api": "https://api.leaseline.app",
  "action": {
    "$id": "https://api.leaseline.app/actions/act_br07HsG8MG",
    "operation": "Lease.renew",
    "status": "done",
    "mode": "do"
  },
  "lease": {
    "$id": "https://api.leaseline.app/leases/lease_4loEed1JG4",
    "$type": "Lease",
    "status": "renewed"
  },
  "links": { "self": "https://api.leaseline.app/actions/act_br07HsG8MG" }
}

Six checks, in order

Step	What is checked	On failure
Address	`api.leaseline.app` resolves to Leaseline's Publication	`404` `not-found`
Key	The key is valid, names one Tenant, and picks `test` or `live`	`401` `unauthorized`; no Action
Version	A version in the path, else the Tenant's `apiVersion`	Answered in that version's shape
Scope and Permissions	The key and the caller's Role allow `Lease.renew`	`403` `forbidden`; no Action
Entitlement	Harbor Residential's Offer grants the Verb	`402` `payment-required`, naming the Offer that covers it
Limit	The call fits the plan's count and rate	The Offer's `atBound`, or `429` `rate-limited` with `Retry-After`

The first four fail at the door, so nothing is recorded. The last two are decisions about the business, so they land on the record.

What the call leaves behind

Record	What it holds
The Action	The Verb, its input, its result, `by` the caller and `for` Harbor Residential
The Event	`Lease.renewed`, numbered by `seq`, kept forever
Deliveries	One per Watch that selects `Lease.renewed` and may read this lease
A Meter Entry	One unit, when the Offer meters the Verb, counted exactly once
The Invoice	The period's metered lines, at the end of the period

The Idempotency-Key makes a retry safe: the same key returns the first Action and runs nothing twice. Idempotency covers the rules.

The same Verb, from the builder plane

Leaseline's Success Manager agent renews leases through api.sb at api.sb/leaseline.app, with its Role's key. The Action, the Event and the Watches are the same.

The address, the key and the scope differ: the agent reaches every Tenant its Role grants, and Harbor Residential's key reaches one. Anatomy of an API compares the two planes.

The callCopy Anchor Link

Six checks, in orderCopy Anchor Link

What the call leaves behindCopy Anchor Link

The same Verb, from the builder planeCopy Anchor Link

The call

Six checks, in order

What the call leaves behind

The same Verb, from the builder plane