Implementation worksheet · 5 min read
An Integration Contract Template for AI App Builders
Write five things down before any integration is built: the operations you actually call (not the whole API), the data crossing the boundary in each direction, the failure policy per call (retry, queue, degrade, or surface), where credentials live and who can rotate them, and the observable signal that tells you the integration is healthy. Describing an integration to a builder without these produces a happy-path call and nothing else — the code works in the demo and fails silently the first time the vendor returns 503. The contract is also the test plan: every row is something you can verify before launch.
Generated apps are very good at the call and, unprompted, uniformly bad at everything around it. The contract is how you make failure handling part of the spec instead of a thing discovered in production.
Put it into practice
1. List the operations, not the integration
'Stripe' is not a scope. 'Create a checkout session, read a session, receive checkout.session.completed' is. Most integrations touch three or four operations; naming them stops the builder generating a wrapper around an entire SDK you will never use.
2. Write the data crossing each boundary
Fields out, fields back, and which of them you persist. This surfaces the privacy question early — if you are storing a full address to display an order status, decide that deliberately rather than inheriting the vendor's payload shape.
3. Set a failure policy per operation
Retry with backoff (idempotent reads), queue and retry later (non-urgent writes), degrade to a documented fallback (show cached status), or surface to the user (payment declined). The default of 'throw and show a spinner forever' is chosen by not choosing.
4. Name where credentials live and who rotates them
Server-side environment configuration, never the browser bundle; one rotation owner; and a note on what breaks during rotation. An API key in a client-side build is the single most common defect in AI-generated integrations.
5. Define the healthy signal
One observable thing that proves the integration works: last successful sync timestamp, webhook received in the past hour, error rate under a threshold. Without it, an integration that stopped working three weeks ago looks identical to one that is idle.
Integration contract (one row per operation)
Copy this structure into your review document and record your observed result for each row.
| Operation | Data out / back | Failure policy | Credential + owner | Healthy signal |
|---|---|---|---|---|
| create checkout session | cart, amount / session id | surface to user | STRIPE_SECRET, server, finance | session created in last 24h |
| read order status | order id / status | degrade to cached | same | cache age < 15m |
| receive webhook | event / ack | verify, idempotent, 2xx fast | signing secret, backend | event received last hour |
| sync inventory | sku list / counts | queue + retry | vendor key, ops | last sync < 1h |
| send notification | message / id | retry x3 then log | provider key, ops | failure rate < 1% |
A failure worth checking
The silent-credential failure: the builder is asked for 'a Stripe integration', puts the key in client-side code because that is where the fetch lives, and the app works perfectly. It keeps working until someone opens the network tab. Naming the credential's location in the contract costs one line and is the difference between a demo and something you can charge for.
Common questions
Is this overkill for a small app?
The contract is five rows and takes twenty minutes. The alternative is discovering your failure policy during your first vendor outage, with customers watching. Small apps fail harder here, not less — they have no operations team to notice.
What if I do not know the failure modes yet?
Read the vendor's status page history and their rate-limit documentation; both tell you what breaks and how often. Write the policy as a guess with a date on it, then revisit after the first real failure.
Basis and scope
This is a proposed implementation method using illustrative examples, not a measured benchmark or a customer case study. Prepared with AI assistance. Validate product-specific behavior against current documentation and your own test environment.