An API (application programming interface) is the set of requests one piece of software agrees to accept from another, and the answers it promises to send back.
It is how your weather app gets a forecast, or your shop takes a card payment, without either one knowing how the other works inside.
The waiter between you and the kitchen
A restaurant is the classic way to picture it. You want a meal, but you don't walk into the kitchen and cook it yourself. You tell the waiter what you want, the waiter takes the order to the kitchen, the kitchen prepares it, and the waiter brings it back.
Mapped onto software:
- You, the diner, are the user, or more exactly the app working on your behalf. Developers call this the client: a browser, a phone app or another program.
- The waiter is the API. It takes requests in an agreed form and delivers the results.
- The kitchen is the server: the code, the database and everything else that does the work.
You never go into the kitchen, and you don't need the recipe. You only need to know how to order.
What an API actually defines
If the waiter is the API, the menu is its documentation. An API sets out:
- What you can ask for: on a web API these are usually endpoints, addresses such as
/weatheror/orders/42, each with the actions it allows. - How to ask: which parameters to send, in what format, and how to prove who you are, often with an API key or a token.
- What comes back: the shape of a successful answer, and how failures are reported.
- The house rules, such as 'no more than 60 requests a minute'.
Wondering how this was made? How we make these