Notes Tutorials

APIs and integration

Calling other systems, and being called by them. What an API is, JSON, why every request needs a timeout, retrying the right way, rate limits, pagination, idempotency keys so a retry doesn't charge twice, and verifying webhooks. Run against a small mock API, in Python and PHP.

7 min readAlso available in Bahasa Indonesia →

Almost no application works alone anymore. It sends emails through one service, takes payments through another, checks shipping rates with a courier, syncs with an accounting system, and maybe calls an AI model. Each of those is an API. Integration code is where many of the hardest production bugs live, because now you’re depending on a system you don’t control, over a network that sometimes fails.

Part 18 covered HTTP itself. This part is about using it to talk to other systems reliably.

An API is a contract

MDN: “An API (Application Programming Interface) is a set of features and rules that exist inside a software program (the application) enabling interaction with it through software - as opposed to a human user interface.” And the key idea: “The API can be seen as a simple contract (the interface) between the application offering it and other items”.

It’s the same idea as a function from part 7 or an abstraction from part 11: inputs, outputs, and a promise, with the inside hidden. The difference is that this function runs on someone else’s computer, may be slow, may be down, and may change.

Most web APIs today exchange JSON: “JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax.” Objects, arrays, strings, numbers, booleans, and null. Every language can read and write it.

The examples below run against a small mock API on the local machine, written to misbehave on purpose: one endpoint is slow, one fails twice before working, one rate-limits, and one takes payments.

Rule 1: every request needs a timeout

The requests documentation is blunt: “By default, requests do not time out unless a timeout value is set explicitly. Without a timeout, your code may hang for minutes or more.” And: “Most requests to external servers should have a timeout attached, in case the server is not responding in a timely manner.”

try:
    requests.get(f"{BASE}/slow", timeout=2)
except requests.Timeout:
    print("slow: gave up after 2 s")
slow: gave up after 2 s

Without that timeout=2, a single slow partner can tie up every worker in your application while they all wait. In PHP with curl, set both a connect timeout and a total timeout:

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 2,
    CURLOPT_TIMEOUT => $timeoutSeconds,
]);
GET http://127.0.0.1:8098/slow failed: Operation timed out after 2002 milliseconds with 0 bytes received
GET http://127.0.0.1:8098/nope returned HTTP 404

Note that curl, like fetch in part 18, doesn’t treat a 404 as a failure by itself. The wrapper checks the status and throws, following part 13.

Rule 2: retry only what’s worth retrying

Some failures are temporary: a 503 while the other side restarts, a network blip, a timeout. Trying again a moment later often works. Others are permanent: a 400 because your request is wrong, a 401 because the key is invalid. Retrying those just repeats the mistake.

A simple retry with exponential backoff: wait a little, then twice as long, then twice as long again, so a struggling service isn’t hammered:

def get_with_retry(url, attempts=4):
    for attempt in range(1, attempts + 1):
        res = requests.get(url, timeout=5)
        if res.status_code == 429:
            wait = int(res.headers.get("Retry-After", "1"))
        elif res.status_code >= 500:
            wait = 0.2 * 2 ** (attempt - 1)
        else:
            return res
        print(f"  attempt {attempt}: {res.status_code}, waiting {wait} s")
        time.sleep(wait)
    res.raise_for_status()
  attempt 1: 503, waiting 0.2 s
  attempt 2: 503, waiting 0.4 s
flaky: {'ok': True, 'attempt': 3}

Two failures, then success, and the caller never knew. Real code usually adds a little randomness (“jitter”) to the wait so many clients don’t retry in lockstep, and limits the total time spent.

Rate limits: 429 and Retry-After

Most APIs limit how often you can call them. “The HTTP 429 Too Many Requests client error response status code indicates the client has sent too many requests in a given amount of time.” And: “A Retry-After header may be included to this response to indicate how long a client should wait before making the request again.”

The retry function above already respects it:

  attempt 1: 429, waiting 1 s
limited: {'ok': True}

If you keep hitting limits, the fix is usually upstream: cache results, batch requests, or stop calling the API inside a loop (the same shape as the query-in-a-loop from parts 10 and 11).

Pagination: there’s always more

APIs rarely return everything at once. They return a page and tell you how to get the next one, with a page number, a cursor, or a next link. Forgetting this is a classic bug: the integration works perfectly in testing with 20 records and silently ignores everything after the first page in production.

products, page = [], 1
while page:
    body = requests.get(f"{BASE}/products", params={"page": page}, timeout=5).json()
    products += body["data"]
    page = body["next_page"]
products: 7 [1, 2, 3, 4, 5, 6, 7]

Seven products across three pages of three. A version that only read the first response would have reported three.

Idempotency: retrying without paying twice

Retrying a GET is harmless. Retrying a POST /payments is not. If the request timed out, you don’t know whether the payment went through, and sending it again might charge the customer twice.

Payment APIs solve this with idempotency keys. Stripe’s documentation: “The API supports idempotency for safely retrying requests without accidentally performing the same operation twice.” And: “A client generates an idempotency key, which is a unique key that the server uses to recognize subsequent retries of the same request.”

The mock API supports the same header. Sending the same payment twice, without and with a key:

headers = {"Idempotency-Key": key} if key else {}
requests.post(f"{BASE}/payments", json={"amount": 150000}, headers=headers, timeout=5)
payments without key: sent twice → ids [1001, 1002]
payments with key: sent twice → ids [1003, 1003]

Without the key, two payments. With it, the server recognizes the retry and returns the first result. Generate the key once per operation (a UUID, or something tied to your order ID), store it with the order, and reuse it on every retry. If you build an API that creates things, consider offering the same.

Webhooks: when they call you

Polling (“is the payment done yet?”) wastes requests. Many services instead send a webhook: an HTTP POST to a URL you provide when something happens. Now you’re the server, and anyone on the internet can send a request to that URL. So you must check that it really came from the service.

The common method is a signature: the service computes an HMAC of the request body with a secret you both know, and sends it in a header. GitHub’s docs: “You can use a webhook secret to verify that a webhook delivery is from GitHub.” and “GitHub uses an HMAC hex digest to compute the hash.” Most payment gateways and SaaS platforms use a similar signature scheme; the exact header, algorithm, and what gets signed differ, so check each provider’s docs.

def is_valid(body, header):
    expected = "sha256=" + hmac.new(SECRET, body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)
genuine:  True
tampered: False

Change one character in the body and the signature no longer matches. Two details matter:

  • Compute the HMAC over the raw body bytes, exactly as received, before parsing the JSON.
  • Compare in constant time. compare_digest “uses an approach designed to prevent timing analysis by avoiding content-based short circuiting behaviour”. A plain == can stop at the first different character, and the time difference can leak information.

In PHP, hash_equals is the equivalent, a “Timing attack safe string comparison”:

$expected = 'sha256=' . hash_hmac('sha256', $body, $secret);
var_dump(hash_equals($expected, $header));                          // bool(true)
var_dump(hash_equals($expected, 'sha256=' . str_repeat('0', 64)));  // bool(false)

Also expect the same webhook to arrive more than once; services retry when you don’t answer fast enough. Handle each event idempotently (check whether you’ve already processed that event ID), answer quickly with 2xx, and do slow work afterwards.

Habits for integration code

  • Keep secrets out of code. API keys and webhook secrets go in environment variables or a secret manager, never in the repository (part 16).
  • Wrap each external API in one place. One module or class per service, with timeouts, retries, and error handling built in. The rest of the code calls courier.shipping_rate(...), not raw HTTP.
  • Validate what comes back. External data is input. Check that fields exist and have the types you expect before using them, just like user input.
  • Log requests and responses (without secrets or personal data), with IDs you can search. When a partner says “we never received it”, logs are your evidence.
  • Read the docs for limits and versions. Rate limits, page sizes, deprecation dates. APIs change; pin the version you use.
  • Test against a fake. A mock like the one in this part lets you test timeouts, retries, and odd responses without calling the real service.

Why this matters day to day

  • The network will fail. Timeouts and retries are the difference between a slow partner and a full outage of your own app.
  • Money and duplicates. Idempotency keys are what keep a retry from becoming a double charge or a double shipment.
  • Security. An unverified webhook URL is a way for anyone to mark orders as paid.
  • AI-generated integration code often skips timeouts, ignores pagination, and compares signatures with ==. Those are now on your checklist.

Try it yourself

  1. Find every outgoing HTTP call in a project you work on. Does each one have a timeout?
  2. Write a client for a paginated public API and check that it reads every page.
  3. Add an idempotency key to an operation in your code that creates something (an order, a payment, an email send).
  4. Implement webhook signature verification for a service you use, and test it with a tampered body.

Summary

  • An API is a contract between programs; most web APIs exchange JSON over HTTP.
  • Always set timeouts. Without one, a slow partner can hang your app.
  • Retry temporary failures (5xx, timeouts, 429) with backoff; don’t retry 4xx mistakes.
  • Respect rate limits and Retry-After; reduce calls with caching and batching.
  • Follow pagination to the end.
  • Use idempotency keys so retries don’t repeat side effects.
  • Verify webhooks with an HMAC over the raw body and a constant-time comparison; handle duplicates.
  • Wrap each API in one place, keep secrets out of code, validate responses, and log.

References