APIs, JSON and how separate systems work together

What an API is

An API (application programming interface) is the defined way one piece of software asks another to do something. It lists what can be requested, what must be supplied, what comes back and what can go wrong. The word that matters is defined: an API is a contract. The provider promises to keep it working; the consumer promises to use only what it describes.

A restaurant is the usual analogy. The menu lists what you can order and what each dish contains; the waiter carries your order to the kitchen and brings the result back. You do not walk into the kitchen, and you do not need to know whether the chef uses gas or induction. The kitchen can change its equipment, staff and suppliers at will, as long as the dishes on the menu still arrive as described. The menu is the API, the kitchen is the implementation, and the separation between them is what lets both sides change independently.

This is the same idea as the interfaces in organising code, applied at every scale. It is also why architects care so much about APIs: an API is where one team's work meets another's, and once others depend on it, it is expensive to change.

In-process APIs and web APIs

Some APIs are called inside one running program. When Python code calls json.loads(text), it uses the API of the standard library's json module: a function call that takes nanoseconds and fails only if the input is bad. A library's public functions and classes are its in-process API.

A web API is called over a network, usually with HTTP (see how computers talk). The caller and the provider can be on different machines, written in different languages and owned by different organisations. A mobile banking app talks to the bank's web API; the bank's servers talk to a card network's API; a shop talks to a payment provider's API.

The difference is not cosmetic. A network call is thousands to millions of times slower than a function call, and it can fail in ways a function call cannot: the network drops the request, the server is overloaded, the answer arrives after the caller has given up, or the request succeeded but the response was lost, so the caller cannot tell whether the payment went through. Much of distributed-systems design, covered in Chapter 6, is about living with these failures.

REST: resources, URLs and verbs

Most web APIs today follow the style called REST (Representational State Transfer), described by Roy Fielding in his 2000 doctoral dissertation. Fielding defined REST as a set of constraints for large networked systems such as the web; in everyday use, "a REST API" means something simpler: an HTTP API organised around resources.

A resource is a thing the API exposes: a customer, an order, a forecast. Each has a URL, such as /orders/1042. A collection of them also has a URL, such as /orders. The client acts on resources with the standard HTTP methods, reads the result's status code, and exchanges data in the body, usually as JSON. The same few verbs therefore work for every resource, which makes well-designed REST APIs predictable.

Status codes carry meaning a client program can act on. A 4xx code says the client did something wrong: 400 for a malformed request, 401 when credentials are missing or invalid, 403 when the caller is known but not allowed, 404 when the resource does not exist, 429 when it has sent too many requests. A 5xx code says the server failed: 500 for an unexpected error, 503 when it is temporarily unavailable. The distinction matters because retrying a 4xx request unchanged will fail again, while retrying a 503 a little later may succeed.

Data travels as JSON (JavaScript Object Notation), a text format standardised as RFC 8259. It has only a few building blocks: objects (name-value pairs inside braces), arrays (lists inside brackets), strings in double quotes, numbers, true, false and null. Despite the name, every mainstream language can read and write it, which is why it became the common language of web APIs. Other styles exist and suit different needs: GraphQL lets the client specify exactly which fields it wants, and gRPC uses a compact binary format for fast service-to-service calls; Chapter 6 compares them.

GET /v1/forecast?city=Kigali&days=2 HTTP/1.1
Host: api.example.com
Authorization: Bearer sk_test_4f9a...
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "city": "Kigali",
  "units": "metric",
  "days": [
    {"date": "2026-10-23", "min_c": 16, "max_c": 27, "rain_chance": 0.6},
    {"date": "2026-10-24", "min_c": 16, "max_c": 26, "rain_chance": 0.4}
  ]
}

import os
import requests

API_KEY = os.environ["WEATHER_API_KEY"]   # never hard-code secrets

resp = requests.get(
    "https://api.example.com/v1/forecast",
    params={"city": "Kigali", "days": 2},
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=3,                 # give up after 3 seconds
)
resp.raise_for_status()        # raises an error for 4xx and 5xx
tomorrow = resp.json()["days"][0]
print(tomorrow["max_c"], "degrees, rain chance", tomorrow["rain_chance"])

Who is calling? API keys and tokens

Most APIs need to know who is calling, to bill them, limit them and decide what they may see. Two ideas are worth separating from the start. Authentication answers "who are you?"; authorisation answers "what are you allowed to do?"

An API key is a long secret string that identifies the calling application, sent with each request, typically in a header. It is simple, and it identifies a program rather than a person. An access token is a short-lived credential issued after someone signs in, often on behalf of a particular user and with particular permissions ("read this user's calendar, but not their email"); it is usually sent as Authorization: Bearer <token>. Tokens expire, so a stolen one is useful for a limited time. The standard protocols behind them, OAuth 2.0 and OpenID Connect, are covered in identity and access.

Whichever is used, the rules are the same: send credentials only over HTTPS, keep them out of source code and out of mobile apps where anyone can extract them, store them in a secrets manager or environment settings, and be able to revoke and replace them quickly.

Webhooks: the API calls you back

Sometimes the client needs to know when something happens on the provider's side: a payment succeeds, a parcel is delivered, a document is signed. The client could poll, asking "has it happened yet?" every few seconds, which wastes requests and still notices late. A webhook reverses the direction: the client registers a URL of its own, and the provider sends an HTTP POST to that URL when the event occurs. The term was coined by Jeff Lindsay in 2007.

Webhooks bring responsibilities. The receiving endpoint is on the public internet, so it must check that each call really comes from the provider, usually by verifying a cryptographic signature in a header. Providers retry when the receiver does not answer, so the same event can arrive twice and the receiver must recognise duplicates (processing a duplicate must not ship the order twice). And events can arrive out of order.

Waiting for an answer, or not: synchronous and asynchronous

Everything so far has been synchronous: the caller sends a request and waits for the response before continuing, like a phone call. It is simple to reason about, and it is the right choice when the caller genuinely needs the answer now, such as "was this card payment approved?". Its weakness is that the caller is only as available and as fast as everything it is waiting on.

The alternative is asynchronous messaging, more like leaving a letter in a post box. The sender puts a message into a message queue and carries on. The receiver takes messages from the queue when it is ready. If the receiver is slow or down for an hour, messages wait instead of failing. When the shop confirms an order, sending the confirmation email does not need to hold up the customer's screen; a message saying OrderPlaced can go into a queue for the email service to handle a moment later.

Asynchrony is not free. The sender does not learn at once whether the work succeeded, the system becomes harder to trace and test, and messages may be delivered more than once. Deciding which interactions should be synchronous and which asynchronous is one of the central decisions in distributed systems, treated properly in communication and APIs and queues and back pressure.

Living with other people's APIs: SDKs, versions and limits

Many providers publish an SDK (software development kit): a library for each popular language that wraps the HTTP calls in ordinary functions, so a developer writes client.refunds.create(payment_id) instead of building requests by hand. SDKs save time and handle details such as retries and signatures, but they are another dependency to keep up to date.

Once an API has users, changing it becomes delicate. Adding a new optional field to a response is usually safe. Renaming a field, removing one, changing its type or meaning, or making an optional input compulsory is a breaking change: every client that relied on the old behaviour breaks, often in production and often for a provider who cannot see or update those clients (think of mobile apps that users never update). Providers therefore version their APIs, for example /v1/ and /v2/ in the URL or a version header, keep the old version running for a published period, and announce deprecations (notices that a feature will be withdrawn) well in advance. Hyrum Wright's observation, known as Hyrum's law, adds a warning: with enough users, someone will depend on every observable behaviour of an API, including ones the documentation never promised.

Providers also protect themselves with a rate limit: a cap such as 100 requests per minute per key. Requests above the limit are refused with status 429 Too Many Requests, often with a Retry-After header saying when to try again. Clients should respect it, spread their requests, cache answers that do not change often, and back off when told to.

Using third-party APIs: build or buy

Modern applications are assembled as much as written. A food-delivery app might use a payment provider's API to take card payments, a mapping API for addresses and routes, an email or SMS API for receipts, and a push-notification service for "your rider is nearby". Each saves months of specialist work and brings expertise (card security, global map data, email deliverability) that few teams could match.

Each also brings a dependency the team does not control: the provider's outages become your outages, its price changes become your costs, its data-handling becomes part of your compliance story, and leaving it may mean rewriting code. Professionals manage this deliberately. They isolate each provider behind a small interface of their own, so that only one part of the code knows the provider's API; set timeouts and decide what happens when the provider is down; watch the provider's status page and change log; and keep a note of what it would take to switch.

Why this matters for architecture

Architecture is largely about the parts of a system and the contracts between them, and APIs are those contracts made concrete. An API that is easy to use correctly and hard to break lets teams work in parallel and change their internals freely; a leaky or unstable one couples everyone to everyone. The choice between synchronous calls and asynchronous messages shapes how failures spread. Chapter 3 explains the principles behind good interfaces (information hiding and abstraction), and Chapter 6 shows how API and messaging choices make or break distributed systems.