Be explicit
Define required fields, allowed values, and how omitted fields differ from null values.
The integration notebook
Good integrations start with clear contracts.
A concise reference for structured data, predictable requests, and thoughtful error handling. Keep the details small. Make the behavior explicit.
About this reference. This is an independent educational website, not an official product API or an affiliated service. All identifiers and payloads below are illustrative; they do not describe live endpoints.
Agree on the request contract
Before connecting two systems, document what a request accepts, what a successful response contains, and which failures a client can recover from.
Keep identifiers stable
Treat resource IDs as opaque strings. Do not infer meaning or ordering from their format.
Bound the work
Set request timeouts and payload limits. Decide how cancellation reaches the calling application.
A resource, with room to evolve
A consistent envelope can separate resource data from metadata. This sample represents a generic collection item; adapt its shape to your own documented contract.
Example resourceIllustrative JSON
{
"data": {
"id": "item_example_01",
"type": "note",
"attributes": {
"title": "A small, useful example",
"created_at": "2026-01-15T09:00:00Z"
}
},
"meta": { "request_id": "req_example" }
}Use unambiguous timestamps
Include a timezone offset in date-time values. Store the original instant and localize its display at the presentation layer.
Allow additive changes
Clients should tolerate unknown response fields. Renaming or removing a field needs an explicit compatibility plan.
Read collections in bounded pages
Cursor-based pagination is useful when collections change between requests. Treat the cursor as opaque and continue only while the response supplies a next cursor.
Example collection envelopeIllustrative JSON
{
"data": [{ "id": "item_example_01" }],
"page": {
"next_cursor": "opaque_example_cursor",
"has_more": true
}
}Set an overall page or time budget, detect repeated cursors, and define how your application handles duplicates. A cursor alone does not guarantee a consistent snapshot.
Make failure a normal code path
Use the provider's documented semantics to decide whether to retry. A status code is a starting point; request safety and the response body matter too.
| HTTP response | Typical client action |
|---|---|
400 / 422 | Inspect validation details and correct the request before resubmitting. |
401 / 403 | Check authentication and permissions. Avoid automatic retry loops. |
404 | Verify the resource identifier and handle absence in the interface. |
429 | Respect Retry-After when supplied; otherwise apply bounded backoff with jitter. |
5xx / timeout | Retry only when safe. A timeout does not prove a write was not applied. |
For write requests, use a documented idempotency mechanism when available. Keep a request identifier in logs, and exclude credentials and sensitive payloads.
A small integration checklist
- Validate configuration and required fields before sending requests.
- Keep service credentials on a trusted server; never embed secrets in public pages.
- Test empty results, malformed responses, timeouts, and partial failures.
- Bound concurrency, retries, pagination, and response sizes.
- Document compatibility assumptions and a safe way to disable the integration.