What Is an API? A Plain-English Guide with Examples

Q: What is an API endpoint?

One address in an API, such as https://api.github.com/users/octocat. Each endpoint represents one resource or operation, and the HTTP method you use on it says what you want done.

The short version

A website is built for a person: it sends pages, and a human reads them and clicks. An API is built for a program: it sends data in a predictable shape, and code reads it. Both usually travel over the same protocol, HTTP, and often come from the same company. A weather service has a website where you look up the forecast, and an API where your app asks for the same forecast as numbers it can use.

The word interface is the important one. An API hides how the other system works and exposes only what you may do with it. You do not need to know which database a payment company runs to charge a card; you need to know the address to send the request to, the fields it expects, and what it will answer. That agreement is the API. The code behind it can be rewritten completely without breaking you, as long as the agreement holds.

One real request, taken apart

Here is a complete exchange with GitHub's public API. It needs no account and no key, so it is a good first request.

GET /users/octocat HTTP/1.1
Host: api.github.com
Accept: application/json

→ 200 OK
  Content-Type: application/json; charset=utf-8

  {
    "login": "octocat",
    "id": 583231,
    "type": "User",
    "public_repos": 8
  }

Every HTTP API call is made of the same few parts:

Part	In the example	What it is for
Endpoint	`https://api.github.com/users/octocat`	The address of the thing you are asking about. An API is a set of these.
Method	`GET`	What you want done: read, create, change or delete. See HTTP methods.
Request headers	`Accept: application/json`	Details about the request: the format you want, who you are, what you are sending. See HTTP headers.
Request body	None — a read needs no body	The data you are sending, when you are creating or changing something.
Status code	`200`	Whether it worked, as a three-digit number. See the status code reference.
Response body	The JSON object	The answer, usually as JSON.

Change the last part of the address to another username and you get another user. Change the method to DELETE and GitHub answers 404, because nobody may delete a user through that address. The API decides what is allowed, and the documentation tells you before you try.

What people mean by “API”

The term is older than the web and covers more than HTTP. A programming language's standard library is an API. So is the set of functions an operating system offers to applications, and the methods a browser gives to JavaScript, such as fetch. In each case one piece of code offers a documented surface to another.

In everyday use, though, “an API” nearly always means a web API: a service reached over HTTP that answers with data. Those come in a handful of styles.

Style	How a call looks	Typical use
REST	Many URLs, one per resource; the HTTP method says what to do; JSON bodies	Most public APIs
GraphQL	One URL; the request body is a query naming exactly the fields wanted	Apps that need many related objects in one round trip
SOAP	One URL; an XML envelope describes the operation; a WSDL file describes the service	Banking, government and older enterprise systems
gRPC	Function calls encoded as Protocol Buffers over HTTP/2	Services talking to each other inside one company
Webhooks	The direction is reversed: the service calls your URL when something happens	Payment, repository and messaging events

APIs are also sorted by who may use them. A public API is open to any developer who signs up. A partner API is offered to named companies under an agreement. A private or internal API is used only by the organisation's own apps — the mobile app you use every day is almost certainly talking to one.

Keys, tokens and limits

The GitHub example works without identifying yourself, which is unusual. Most APIs want to know who is calling, both to protect private data and to count usage. The usual credential is an API key: a long random string issued when you sign up, sent with every request in a header.

GET /v1/forecast?city=Leeds HTTP/1.1
Host: api.example.com
Authorization: Bearer sk_live_9f2c41…

Send no key, or a wrong one, and the answer is 401 Unauthorized. Send a valid key that is not allowed to do what you asked, and it is 403 Forbidden. Call too often and you get 429 Too Many Requests, because nearly every API applies a rate limit. The guide to API authentication compares keys with the other schemes, including OAuth, which is what you need when an app acts on behalf of a user rather than for itself.

Why APIs exist

To avoid rebuilding what exists. Sending a text message, taking a card payment or drawing a map are each years of work. An API lets you rent the result with a few requests.
To let one back end serve many front ends. A website, an iPhone app and an Android app can all read and write the same data through one API.
To connect systems that were not built together. When a new order in a shop appears in an accounting package, an API call carried it there.
To give a stable contract. The team behind the API can change languages, databases and servers freely, as long as the documented requests keep working.

Send your first request

Open the API tester, leave the method on GET, enter https://api.github.com/users/octocat and press Send. You will see the status code, the time taken, every response header and the JSON body. Then try an address that does not exist, such as https://api.github.com/users/this-user-does-not-exist-000, and read the 404 and the error message in its body. Reading a failure calmly is most of what working with APIs involves.

The same request from a terminal is one line: curl https://api.github.com/users/octocat. The curl GET example walks through it, and REST API testing covers what to check once the first call works. For provider-specific starting points, the API testers are pre-filled for OpenAI, GitHub, Slack and others.

References

MDN: Introduction to web APIs — What APIs are, from the browser's point of view.
RFC 9110: HTTP Semantics — The specification for methods, status codes and headers that web APIs are built on.
GitHub REST API: Users — Documentation for the endpoint used in the example on this page.

These links leave api-tester.com, which is independent of the organisations they point to.

Frequently asked questions

What does API stand for?

Application programming interface. It is the documented set of requests one piece of software accepts from another, together with the form of the answers.

What is an API in simple terms?

A way for programs to ask each other for things. Your code sends a request to an address the other system publishes, and gets data back in an agreed format, most often JSON over HTTP.

What is the difference between an API and a website?

A website returns pages laid out for a person to read. An API returns structured data for a program to use. Many companies offer both over the same protocol, and the website is often itself a client of the API.

What is an API endpoint?

One address in an API, such as https://api.github.com/users/octocat. Each endpoint represents one resource or operation, and the HTTP method you use on it says what you want done.

Do I need an API key to use an API?

Usually. A few public APIs allow anonymous calls at a low rate limit, but most require a key or token so they can identify the caller. A missing or invalid key is answered with 401 Unauthorized.

Is an API the same as REST?

No. REST is one style of web API, and the most common. GraphQL, SOAP and gRPC are other styles, and the word API also covers libraries and operating system interfaces that have nothing to do with HTTP.