What is an API?

An API (application programming interface) is a defined way for one piece of software to ask another for data or to get something done. Instead of a person clicking through screens, a program sends a request in an agreed format and gets a response in an agreed format.

Think about the sign-up form for a weekend class. If every new sign-up gets copied by hand into a spreadsheet or customer list, that’s a job an API can take over, as long as both tools offer one. Knowing the basics helps you judge whether a tool will work with the others you use, and what to watch for when you connect them, such as keeping keys safe and staying within limits.

What are APIs for?

Most web services have two front doors: screens for people and an API for programs. Screens are designed to be pleasant to look at, and their layout changes as the design evolves. An API is designed for programs to read and write, so its shape is fixed and documented.

With APIs, you can for example:

• Take payments on an online course site through a payment provider’s API
• Add each inquiry from a small company’s contact form to a customer management tool automatically
• Pull the numbers you used to collect by hand every week into a spreadsheet or your own report

The word “API” can also mean any defined interface between pieces of software, such as the functions a programming library offers. This article is about web APIs, which you call over the internet using HTTP, the same protocol a browser uses to load web pages. MDN’s overview of HTTP explains the protocol in more depth.

How does an API work?

Working with an API is a lot like visiting a service counter at a town hall or a bank. Each counter handles particular requests. You fill in the right form, show who you are, hand it over and get a reply in a standard format.

At the counter	In an API
Which counter you go to	Endpoint (a URL)
Whether you’re asking, applying, changing or cancelling	HTTP method
The form you filled in	Request body
ID or a letter of authority	API key or other credentials
The reply and whether it was accepted	Response and status code

A typical exchange goes like this:

1. A program sends a request to an endpoint with an HTTP method.
2. The API checks who’s asking, usually with an API key.
3. It checks the input against its rules and does the work.
4. It sends back a response.

The comparison has one big limit: nobody sits behind an API’s counter. A request that’s even slightly off won’t be read generously; it’ll be turned away. That’s why every API comes with a reference, documentation that spells out each endpoint, field and error.

What is an endpoint?

An endpoint is the URL that says which data you’re asking about. For example, https://api.example.com/v1/courses might be the list of courses and https://api.example.com/v1/courses/42 course number 42. The v1 is a version number. Services often use one so that existing integrations keep working when the API changes in a big way.

What are HTTP methods?

The same endpoint can do different things depending on the HTTP method. These five are the most common.

Method	Meaning	Example
GET	Read	Get the list of courses
POST	Create or submit	Register one sign-up
PUT	Replace entirely	Rewrite all of a course’s details
PATCH	Change part	Change only the number of seats
DELETE	Remove	Remove a cancelled sign-up

GET only reads, so under the rules of HTTP, sending it again shouldn’t change anything on the server. POST, on the other hand, usually creates something new each time. If a connection drops and a program simply sends the same POST again, you can end up with two sign-ups instead of one. MDN keeps a list of HTTP request methods.

What are status codes?

Every response carries a three-digit status code. Codes in the 200s mean success, the 400s mean something was wrong with the request, and the 500s mean something went wrong on the service’s side.

Code	Meaning
200 / 201	It worked / something new was created
400	The input doesn’t follow the rules
401	The service can’t tell who’s asking (missing or wrong key)
403	The service knows who’s asking, but that action isn’t allowed
404	The thing you pointed to wasn’t found
429	Too many requests
500	Something unexpected happened inside the service

What is JSON?

Requests and responses usually carry their contents as JSON (JavaScript Object Notation, often pronounced “jay-son”). JSON is a text format that writes data as pairs of names and values, and it’s easy for both people and programs to read.

One sign-up might look like {"name": "Alex Kim", "course": "Beginners", "seats": 1}. Here name and course are names (also called keys), and "Alex Kim" and 1 are values. A value can be text, a number, true or false, null (nothing), a list in square brackets, or another group of pairs nested inside.

Despite the name, JSON doesn’t depend on JavaScript or any other single language, so tools written in different languages can exchange it. An API’s reference tells you which names to expect and what kind of value each one holds.

Why should you keep API keys secret?

An API key is a long string that tells an API who’s making a request. It works like a spare key or a letter of authority. Many APIs expect it in the request’s Authorization header, a note sent alongside the body, after the word Bearer.

Anyone who has your key can use the API as your organization, within whatever the key allows. They could read your data, change it or use up your quota, so treat an API key like a password:

• Don’t put it in code that reaches the browser, such as JavaScript on a web page. Visitors can read it there.
• Don’t share it in public repositories, chat, email or screenshots.
• Store it where secrets belong, such as a server’s environment variables or a tool’s secret settings.
• Use a read-only key when reading is all you need.
• Give each tool its own named key, so you can switch one off without breaking the others.
• Revoke keys you no longer use, and any key that may have leaked, then create a new one.

If a key does leak, there’s no need to panic. Once you revoke it, it stops working. Connect a new key, then check the usage records for any calls you don’t recognize.

What is a rate limit?

A rate limit caps how many requests an API accepts in a given period, such as 10 per second or 1,000 per day. It keeps one buggy or overly busy program from making the service worse for everyone else.

When you go over, the API usually answers with status code 429 (Too Many Requests). Some APIs add a Retry-After header that says how long to wait, but not all of them do. MDN describes 429 Too Many Requests in more detail.

To work well within limits:

• After a 429, don’t retry right away. Wait, and wait a little longer each time it happens again.
• When you have many items to send, use an endpoint that accepts them in one batch if the API has one.
• Keep data you’ve already fetched instead of asking for it again.
• Before automatically retrying a write whose result is unknown, such as a POST, check whether it went through.

Summary

• An API is a defined way for software to exchange data and actions.
• The endpoint says where, the HTTP method says what, and JSON carries the contents.
• Keep API keys as private as passwords, and limit what each one can do.
• When you hit a limit, wait before retrying, and be careful about retrying writes.

For the opposite approach, where a service tells you when something happens, see What is a webhook?.