Use an API only when a bounded data job justifies it

API: define the data contract

Define one decision or handoff, endpoint, schema, authentication, schedule, quota, retry, idempotency, monitoring, privacy boundary, and fallback. Avoid turning a simple workflow into custom infrastructure without a clear return.

Start with the customer or operator decision that api must improve. Record the before-state: audience, offer, current tools, data, handoffs, elapsed time, known exceptions, cost, and accountable person. That prevents api from becoming a configuration exercise with no business job.

A credible conclusion also states the evidence that would reverse it.

• Define what api must accomplish.
• State the evidence that would reverse the answer.

Test fields, events, access, and delay

Build the smallest complete version of api. Preserve source, consent, fields, timing, price or eligibility, downstream action, owner, and a visible completion state. Test a new person, an existing person, missing information, a duplicate event, a delayed event, and the most likely failure.

Prototype the smallest useful request and log the result.

• Name every source and owner.
• Test the normal and exception paths.
• Keep the recovery route visible.

Own failure and recovery

Use five gates: customer clarity, operational reliability, evidence quality, recoverability, and complete cost. A failed gate is not repaired by more features. Decide whether the gap can be configured, needs another tool, requires a human owner, or makes the platform unsuitable.

Keep the api decision reversible until one full cycle passes.

• Compare the same business job.
• Count complete operating cost.
• Protect the customer when something fails.

Approve after one full cycle

Save the purpose, configuration, sources, owner, test records, exceptions, fallback, and next review date. Recheck after product, plan, offer, domain, integration, policy, team, or audience changes.

Proceed when api works for the normal path and the known failure path. Pause when missing access, ambiguous state, or customer obligations make the outcome unsafe.

• Save evidence and configuration.
• Assign the next action.
• Schedule the next review.