“The API is down.” “It’s in the API docs.” “Just call the API.”
If you work in software, you hear the word many times a day. Ask three colleagues what an API actually is, and you may get three answers: a server, a web address, a page of documentation. None of them is quite right.
So what is it? If you work next to APIs and want to know what is actually going on, this guide was written just for you. That means testers, technical writers, product people, and developers who are starting out.
What is an API?
An API (Application Programming Interface) is the way one piece of software asks another for something. It sets what can be asked, how to ask, and what comes back.
People use software through a user interface: screens, buttons, forms. A program can’t click buttons. It needs an interface of its own, with fixed questions and fixed shapes of answers. That interface is the API.
Three things make it up:
- What you may ask. The list of operations the other side offers: get a forecast, find a pet, place an order.
- How to ask. Where to send each question and what to put in it.
- What comes back. The shape of every answer, including the answers for when things go wrong.
Take the weather app on your phone. The phone has no weather station. The app asks a weather service for the forecast, through the service’s API, and draws the answer on the screen.
Notice what is not on the list above: how the other side does its work. The weather service may run on one machine or a thousand. The app does not know and does not need to.
Why do APIs matter?
APIs matter because they let programs use each other’s work without knowing how it is done. Four things follow from that:
- You don’t build everything yourself. The weather app does not forecast weather. A shop does not process cards. Each asks someone who does it well.
- The inside can change. As long as the questions and answers stay the same, the service behind them can be rewritten, moved, or grown, and no caller notices.
- Access can be checked. Every question comes in the same way. The API can check there who is calling and what they may do.
- Work can be automated. Anything a program can ask for once, it can ask for a thousand times.
What kinds of APIs are there?
APIs are either local or remote. A local API is called inside one program or one machine. A remote API is called over a network.
Some APIs are local. “API” is a wide word, and it is older than the web. A programming language has an API: the functions it lets you call. So does every library, every operating system, and every browser. Here is an API call with no network in it at all:
const pet = JSON.parse('{"name":"fido"}');
Your code asked the JavaScript engine to read a piece of JSON, a plain-text format for data, and turn it into an object. JSON.parse is the fixed question. How the engine does the work is its own business.
Some APIs are remote. The two sides are separate programs, usually on different machines, and they talk over a network. Most remote APIs today are web APIs: they travel over HTTP, the set of rules browsers and servers use to talk. The weather service is one, and the program that answers is called the server. Remote APIs come in several styles, and most of them travel over HTTP:
- REST uses HTTP as it was designed. HTTP’s own methods, addresses, and status codes are its vocabulary.
- GraphQL sends one query that names exactly the fields wanted.
- gRPC calls remote functions in a compact binary format. It is often used between services inside a company.
- SOAP wraps every message in XML. It is older and still in use in many enterprise systems.
- Event-driven APIs turn the direction around. You don’t ask. The other side tells you when something happens. A webhook works this way: you give the other side an address of yours, and it calls you.
APIs are also sorted by who may call them: private, partner, and public. The FAQ at the end has that list.
When people say “API” today, they most often mean a web API, and the style you are most likely to meet is REST. So the next sections explain REST and then follow one REST call from start to end. Keep in mind that REST is one kind of API, not the only one. The idea that comes after it, the contract, holds for every kind.
What is a REST API?
A REST API is an API built on plain HTTP. Each thing it knows about has a URL, and the HTTP methods say what to do with it.
REST stands for Representational State Transfer. The name comes from Roy Fielding’s doctoral dissertation from 2000. A REST API borrows the habits of the web itself:
- Everything is a resource with a URL. In a pet shop’s API a pet is a resource, and pet 99 lives at
/pet/99. - The methods are the verbs. You don’t call
getPetorremovePet. You sendGETorDELETEto the pet’s URL. - The answer is a representation. You don’t get the pet itself. You get a description of it, usually in JSON. The same pet could be sent as XML, an older text format for data.
- Every request stands on its own. The server keeps the data, the pets. It does not keep track of the conversation with you. Each request carries everything needed to answer it, including who is asking. This is what “stateless” means.
Not every API that speaks HTTP is strictly REST. Fielding’s rules go further than these four, and few APIs keep all of them. In everyday speech “REST API” has come to mean an HTTP API that has URLs for its resources and answers in JSON.
Now let’s watch one work.
A REST API call, taken apart
The Swagger Petstore is a public practice REST API for a pretend pet shop. Anyone can call it. Here we ask it for the pet with the id 99, using curl, a command-line tool that sends requests:
curl -i --http1.1 -H 'Accept: application/json' https://petstore3.swagger.io/api/v3/pet/99
The -i option prints the whole answer, not only its last part. The --http1.1 option asks for the older version of HTTP, whose messages are written as text and are the easiest to read.
And here is what comes back. A few lines are left out, and the last part, which arrives as one long line, is spread out so it is easier to read:
HTTP/1.1 200 OK
Date: Fri, 13 Nov 2026 19:31:37 GMT
Content-Type: application/json
Content-Length: 150
Server: Jetty(9.4.53.v20231009)
{
"id": 99,
"category": { "id": 101, "name": "dogz" },
"name": "fido",
"photoUrls": ["http://fido.jpg"],
"tags": [{ "id": 102, "name": "friendly" }],
"status": "available"
}
That is the whole thing. One program sent a request, the other sent back a response. A REST call always has these two halves.
The Petstore is open to everyone, and anyone can change its pets. If you run the commands in this guide yourself, the answers may look different.
What is in a request?
The curl command above hides the request behind one line. Here is what it actually sent:
GET /api/v3/pet/99 HTTP/1.1
Host: petstore3.swagger.io
User-Agent: curl/8.5.0
Accept: application/json
A request has four parts:
- The method says what kind of action this is.
GETreads something.POSTcreates,PUTandPATCHchange,DELETEremoves. - The URL says what the action is about. Notice that it arrives in two pieces: the path,
/api/v3/pet/99, on the first line, and the server in theHostline. - Headers are the named lines that follow. They carry information about the request itself.
Accept: application/jsonsays: answer in JSON, please. An API key, a secret that says who is calling, travels in a header too. - The body carries data to the server. Our
GEThas none. APOSTthat adds a new pet would carry the pet here.
The values that change from one request to the next are called parameters. Most of them sit inside the URL. The 99 in the path is a path parameter: the id of the pet. A query parameter rides after a question mark, as in /pet/findByStatus?status=available.
One address an API answers at is called an endpoint. It is usually written as a pattern with a placeholder for the parameter: /pet/{petId}. The /api/v3 in front is the same for every Petstore address, so it is left out of the pattern.
What is in a response?
A response has three parts:
- The status code is the short verdict.
200means it worked. - Headers describe the answer.
Content-Type: application/jsonsays the body is JSON. - The body is the answer itself: a pet named
fido, with the statusavailable.
Status codes come in families, and the first digit names the family. These are the four you will meet:
2xx: it worked.3xx: usually, look somewhere else.4xx: the request was wrong.5xx: the server failed.
Now, what if we ask for a pet that does not exist? Let’s try a number nobody is likely to have used, 987654321. Again a few lines are left out:
HTTP/1.1 404 Not Found
Date: Fri, 13 Nov 2026 19:51:00 GMT
Content-Type: application/json
Content-Length: 13
Pet not found
404 is in the 4xx family: the request asked for something that isn’t there. A program reads that number first and only then decides what to do with the body.
Notice the Content-Type header on this one. We will come back to it.
An API is a contract
Now let’s step back from REST to APIs of every kind. An API is not the software that does the work. It is the agreement about how to ask for the work: ask like this, and the answer will look like that. That agreement is a contract.
Take the Petstore. It’s tempting to think of its API as the server. It isn’t. The server is a machine that can be replaced tomorrow, and the agreement stays. For the call we made, it says something like this:
- Send
GETto/pet/{petId}, wherepetIdis a whole number. - If that pet exists, the answer is
200and the body is the pet. - If it does not, the answer is
404.
Look back at what happened. Pet 99 gave us a 200 and a pet. The pet that does not exist gave us a 404. As you can see, the status codes did not surprise us. The contract said in advance what they would be.
Every API has such a contract, local ones too. For JSON.parse it is short: give it text that is valid JSON and you get the value back. Give it text that is not, and it throws a SyntaxError.
A contract can be written down, in a form that both people and programs can read. Such a document is called an API description. For REST APIs the common format is OpenAPI, and the Petstore publishes one.
It’s important to realize what a contract does not promise:
- That the other side is there. The contract describes the answers. It can’t make a server that is down give them.
- That the data makes sense. The Petstore is public, and anyone can write to it. A pet’s name or category may be nonsense left over from somebody’s test.
- That everyone keeps to it. The Petstore’s written contract says our call needs proof of who is calling: an API key or a login. We sent neither and got an answer anyway. And look at the
404again: theContent-Typeheader says JSON, and the body is plain text, so the server mislabels its own answer. Software is written by people, and people slip. - In what order to make the calls. This one needs a closer look.
Where one call stops
We asked for pet 99 because we already knew the number. But where would the number come from?
From another call. The Petstore can list the pets that are available. That answer is a list, and every pet in it has an id. Take one id out of the first answer, put it into the second request, and you have the pet. Two calls, with something carried from one to the next.
Real work is nearly always like this. Log in, then use the pass you got back, called a token. Create an order, then pay for it, then check that it shipped. One call rarely does a job on its own.
Remember the last thing a contract does not promise: in what order to make the calls. The Petstore’s contract describes each operation, one at a time. It does not tell you to list the pets first and fetch one second. That knowledge lives somewhere else: in a script, in a wiki page, in somebody’s head.
A sequence of calls with a purpose is called an API workflow. Listing the pets and then fetching one is a small one.
So there it is. One API call is a request, a response, and a contract that says what both look like. The contract stops at the single call. What happens between the calls is the next thing to learn.
Next steps
- Try it yourself. The Swagger Petstore page has a “Try it out” button on every operation, so you can send the calls from this guide without installing anything.
- Read a contract. The Petstore’s API description is a small, complete one, written in OpenAPI.
- API Workflows Are Still Improvised picks up where this guide stops: what happens when the order of the calls is written down nowhere.
- Ready to describe a sequence of calls as a document, check it, and run it? Getting Started with UseArazzo does that with the two calls from the last section: list the pets, then fetch one.