What is an API? A plain-language guide with real examples

On the web, an API call is an HTTP request sent to an address called an endpoint. It has a method that says what to do, a path that says to what, optional parameters, and sometimes a body of data. The server replies with a status code and, usually, data. Here is an imaginary weather API:

Request:   GET https://api.example.com/v1/weather?city=Pune
Response:  200 OK
           {"city": "Pune", "temperature_c": 27, "humidity": 61}

The answer above is JSON (JavaScript Object Notation), a text format made of names and values, lists and nested objects. It is easy for people to read and for programs of any language to parse, which is why it became the standard for web APIs. Older systems use XML, and some modern ones use more compact formats, but a developer meets JSON first.

The common methods are GET to read data, POST to create something, PUT or PATCH to change it, and DELETE to remove it. The status code in the response tells the caller what happened.

• 200 means success, and 201 means something was created.
• 400 means the request was malformed, 401 means you have not proved who you are, 403 means you are not allowed, and 404 means the thing does not exist.
• 429 means you have sent too many requests and must slow down.
• 500 and above mean the fault is on the server's side.

Many APIs need to know who is calling. A simple method is an API key, a long random string sent with each request, which lets the provider identify, limit and bill the caller. Where an app acts on behalf of a user, as in Sign in with Google, a protocol called OAuth gives the app a token that allows only what the user agreed to, without giving it the password.

Keys are secrets. A key that is put in the code of a website or an app that anyone can inspect can be copied and abused, so serious applications keep keys on a server and call the API from there.

To protect themselves, APIs set rate limits, a cap on requests in a given time, and return pages of results, with a way to ask for the next page, rather than everything at once. A well-behaved client waits when it is told to, and retries after a pause instead of hammering the server.

Sometimes the flow goes the other way. A webhook is an API call that a service makes to you when something happens, for example when a payment succeeds, so that you do not have to keep asking.

A ride-hailing app asks a maps service for a route and a payments service to take the fare. A payments app on your phone talks to your bank through the interfaces behind UPI. A news reader asks publishers' feeds for the latest items, which is also how Plax receives most of its stories. Even a weather widget on your home screen is an API call every few hours.

Good APIs are designed with the user in mind: clear names, stable versions so that old callers keep working, helpful error messages and honest documentation. Bad ones change without warning, which is why developers read the changelog before upgrading.

• How the internet works: from a tap on your phone to a web page

  What happens in the second after you open a website: IP addresses, DNS, packets, HTTPS and the cables under the sea, explained without jargon.

• How AI chatbots and summaries work, and why they sometimes get things wrong

  Large language models predict text. That makes them fluent and useful for summaries, and it also explains why they can state falsehoods with confidence.