API integration

What every API integration must handle

Authentication: keys and OAuth

APIs commonly use either a secret key or OAuth. OAuth 2.0, defined in RFC 6749, lets an application obtain limited access to a service on behalf of a user or account, usually through a token that expires and must be refreshed. Whichever method an API uses, credentials must be stored as secrets, never in code or shared documents, scoped to the minimum permissions needed and renewed before they expire. An integration that stops when a token quietly expires is a common, avoidable failure.

Use separate credentials per integration so one can be revoked without affecting others.

Rate limits and slowing down

APIs limit how many requests you may make in a period. RFC 6585 defines the 429 Too Many Requests status for this, and responses may include a Retry-After header saying how long to wait. A well-built integration watches for these signals, waits before trying again and spreads bulk work over time rather than firing thousands of requests at once. Ignoring limits can lead to blocked access at exactly the moment volumes are highest.

Check each vendor's documented limits, which often differ by plan.

Retrying without duplicates

Pagination: getting all the data

APIs rarely return thousands of records in one response. Instead they return a page of results with a way to fetch the next, such as a page number, an offset or a cursor. Integrations that read only the first page work in testing with small data and then quietly miss records in production. Follow the vendor's pagination method to the end, handle records that change while you are paging and, for large data sets, prefer the vendor's change feeds or 'modified since' filters over re-reading everything.

Record where each sync stopped so the next run can continue from there.

Versions and deprecations

Vendors release new API versions and retire old ones, usually with notice. Build against a current, supported version, subscribe to the vendor's developer announcements and plan updates before deprecation dates. Test against new versions in the sandbox before switching. An integration built on an old version may keep working for a while, then fail on a fixed date.

Sandboxes and test data

Many APIs provide a sandbox or test account that behaves like the live system without affecting real data. Develop and test there first, including error cases such as invalid data, expired tokens and rate limits. Where no sandbox exists, agree a careful plan for testing against live data with clearly marked test records.

Running it reliably

Queues for failed items, alerts and reconciliation keep integrations healthy after launch; the software integration services page covers those operating practices in detail.

Timeouts

Set sensible timeouts on every call, so a slow vendor does not hold up your own system indefinitely.