What Is an API and How Does It Work?

Published:

16 minute read

Acar Diveroli
Written by: Acar Diveroli
A phone sends a request card with a blue key to a server and gets back a card of JSON lines; label API above

You open a weather app and tomorrow's forecast appears in a second. The phone did not work it out: the app sent a short message to the weather service's server asking for one city, and got back a few lines of plain data that it turned into icons and numbers. The same thing happens when a shop's checkout asks a payment company to charge your card, or when a colleague says "just use their API, here is your key".

This post follows one API call from request to response, with real output from our own test, then covers methods, status codes, API types, keys, rate limits, versioning and key safety.

What is an API?

An API is the agreed way for one piece of software to ask another for data or for an action. The letters stand for application programming interface: "interface" because it is the meeting point between two programs, "programming" because code uses it, not a person clicking on a screen.

A cash machine is a good everyday picture. It offers a short, fixed menu (check balance, withdraw, change PIN), and you never see the vault behind it. Your card and PIN prove who you are, a daily limit caps how much you take, and a problem gets a short message such as "insufficient funds". An API works the same way: a fixed list of requests, a key that identifies the caller, limits on use and clear error answers.

Operating systems and browsers offer APIs too, but in everyday use "an API" means a web API: a service you call over the internet with HTTP, the protocol your browser uses to load pages.

How does an API call work?

An API call is one request from a program to an API plus the response that comes back. It runs through the same steps every time:

  1. The client builds a request. The client (an app, a script or a server) picks a method (what to do), an endpoint (the address of the operation), headers (extra details such as the key) and, for some methods, a body with data.
  2. The request reaches the server over an encrypted HTTPS connection, after DNS has turned the server's name into an IP address.
  3. The server checks the caller: may this key use this endpoint, and is it still within its limits?
  4. The server does the work, such as reading a database or starting a payment.
  5. The server answers with a status code that says how it went, headers and usually a body with the data.
  6. The client reads the answer. It checks the status code first, then picks the fields it needs by name.

What does an API request and response look like?

A request is a method and an endpoint, headers and sometimes a body; a response is a status code, headers and usually a body:

PartIn the requestIn the response
First lineMethod + endpointStatus code
HeadersKey, data formatData format, limits
BodyData to send (optional)The result, often JSON

You can watch this with curl, a free command-line tool for sending web requests. JSONPlaceholder is a public test API that needs no account or key, so it is a safe place to try:

bash
curl -i https://jsonplaceholder.typicode.com/todos/1

On our test machine, this returned HTTP/1.1 200 OK, the header Content-Type: application/json; charset=utf-8 and this body:

json
{
  "userId": 1,
  "id": 1,
  "title": "delectus aut autem",
  "completed": false
}

The -i flag prints the status line and headers too, and without a method flag curl sends GET, which means "read". A POST to /todos with a small JSON body came back as 201 Created with a new "id": 201; this test API only pretends to save the record, which is what makes it safe for practice. Asking for /todos/999999, a record that does not exist, returned 404 Not Found.

The body format is JSON (JavaScript Object Notation): plain text made of names and values that nearly every programming language can read. Its standard, RFC 8259, requires UTF-8 between systems and names the media type application/json, the value in the header above. Older APIs often answer in XML.

Which HTTP methods do APIs use?

The method is the verb of a request: read, create, change or remove. RFC 9110, the standard that defines what HTTP messages mean, calls some methods "safe" (they only read) and some "idempotent" (sending the same request twice has the same effect as sending it once).

MethodTypical jobSafeIdempotent
GETRead a record or a listYesYes
POSTCreate a record, start an actionNoNo
PUTReplace a recordNoYes
PATCHChange part of a recordNoNot by default
DELETERemove a recordNoYes

The difference matters when a connection drops halfway. Repeating a GET is harmless; repeating a POST may create a second order or a second payment. That is why many APIs accept an idempotency key with a POST, a unique value that tells the server "if you already did this one, do not do it again".

What do API status codes mean?

The status code is the three-digit number at the top of every response, and its first digit says who is responsible: 2 means success, 3 means the client must take a further step such as following a redirect, 4 means the request was wrong and 5 means the server failed. The codes you meet most with APIs:

  • 200 OK and 201 Created: the request worked; 201 means a new record was made.
  • 400 Bad Request: the request is malformed, often a missing field or broken JSON.
  • 401 Unauthorized: no valid key or token was sent.
  • 403 Forbidden: the server knows who you are, but you may not do this.
  • 404 Not Found: the endpoint or the record does not exist.
  • 429 Too Many Requests: you went over the rate limit.
  • 500 Internal Server Error: the server failed while handling the request.

A well-built API explains the error in the body as well. When we called our own API's /me endpoint without a token, it returned 401 Unauthorized, a www-authenticate: Bearer header naming the expected scheme, and a JSON body with an error code, a one-line message ("Missing or malformed Authorization header") and a request ID to quote to support.

What types of APIs are there?

Web APIs differ mainly in how requests are shaped, and four styles cover most of what you will meet:

TypeHow you askTypical use
RESTOne address per resourceMost public web APIs
GraphQLOne endpoint, you list fieldsApps needing flexible data
gRPCCalls defined in a schema fileBetween internal services
WebhookThe service calls youEvent notices

REST (representational state transfer) gives each thing its own address, such as /orders/42, and acts on it with the HTTP methods above. When people say "an API" without more detail, they usually mean a REST-style JSON API. GraphQL sends every request to one endpoint, and the client's query lists exactly the fields it wants back. gRPC defines each call in advance in a schema file and by default sends data as Protocol Buffers, a compact binary format.

Webhooks turn the direction around: instead of your program asking "anything new?" every minute, you give the service a URL of yours, and it sends a request there when something happens, such as "payment received".

APIs also differ by who may use them. A public API is open to any developer who signs up, a partner API only to companies under a contract, such as a marketplace's seller integration, and a private API only to the company's own apps and services.

What is an API key, and how is it different from a token?

An API key is a long secret string that identifies the program calling the API, like the card in the cash machine. The server checks it on every request to decide who is calling, what that caller may do and which limits apply, and it usually stays valid until you revoke it.

A token does the same job but is usually issued for a shorter time or a narrower purpose. OAuth 2.0 is the standard behind most "connect your account" screens: you approve an app on the service's own page, and the app receives an access token limited to the permissions (scopes) you approved, without ever seeing your password. Many such tokens are bearer tokens, defined in RFC 6750: whoever holds one can use it, so it travels in the Authorization header and never in a page URL.

MethodWhat it provesTypical use
API keyWhich program or account callsServer-to-server calls
OAuth tokenWhat a user allowed an appConnected accounts
IP allowlistWhere the call comes fromBanks, exchanges, B2B

You get a key in the developer or API section of your account on the service's site: create it, tick only the permissions it needs and copy it, since many services show the full key only once. Our own API, described in the Docs section of this site, accepts a bearer token only in the Authorization header, never in the URL or a cookie, and each token carries scopes, so a read-only token cannot place an order.

What is a rate limit?

A rate limit is the number of calls a caller may make in a given time, such as 60 requests per minute per key. It protects the service from overload and keeps one heavy user from slowing everyone else down. Over the limit, the API answers 429 Too Many Requests until the window resets.

Many APIs report your allowance in response headers. Ours sends X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset with every response; these names are a common convention, not a fixed standard, so check each API's documentation. Handling the error when it does come is covered in 429 Too Many Requests and Rate Limit Errors Explained.

How are APIs versioned and documented?

APIs are versioned so that a change on the server does not break programs already calling it. The most visible way is a version in the path, as in our base URL https://api.proxynet.io/api/v1: incompatible changes go into v2, and v1 usually keeps working for an announced period. Some APIs put the version in a header instead.

Documentation is the API's contract: every endpoint with its method, parameters, an example response and its errors. Many APIs publish it in the OpenAPI Specification format, a JSON or YAML file that describes an HTTP API for people and tools alike (version 3.2.1 came out on 10 September 2026). From that file, tools can draw a reference, generate client code or build a "try it" panel.

How do you keep an API key safe?

Treat an API key like a password: anyone who has it can act as you, and on a paid API spend your money. Most leaks are simple:

  • Keys in code. A key pasted into a script ends up in a Git repository; keep it in an environment variable or a secrets manager.
  • Keys in front-end code. Anything shipped to a browser or a mobile app can be read by its users; call the API from your server.
  • Keys in URLs. URLs land in server logs and browser history.
  • One key for everything. Give each integration its own key with the fewest permissions, so one leak can be revoked alone.
  • Keys that never change. Rotate on a schedule and at once after a leak: create the new key, switch over, delete the old one.

On the provider's side, the OWASP Foundation's API Security Top 10 lists the most common API flaws. First on its 2023 list is broken object-level authorization: an endpoint that returns record 42 to anyone who asks, without checking that the caller owns it.

How is an API different from web scraping?

An API returns the data a provider chooses to share, in a documented format and under written limits; web scraping downloads pages built for people and picks the data out of the HTML. The API is steadier when it carries the fields you need, while scraping covers what no API offers but breaks when the layout changes. Both are compared, with the same data fetched both ways, in Web Scraping vs API.

Why do some APIs only accept calls from certain IP addresses?

Some APIs check where a call comes from as well as which key it carries. Banks, crypto exchanges, marketplaces and many business data services let you register IP addresses for a key, an IP allowlist, and refuse calls from anywhere else, so a stolen key does not work on someone else's machine.

Your program then needs a fixed outgoing address, which home lines, laptops and many cloud functions lack; the options are compared in Static IP for API Access.

For test setups and integrations that carry no payment or health data, a ISP Proxy gives a script one dedicated IP to register.

A Datacenter Proxy does the same from a data center address. Both come with a target-site restriction by default, so you name the API's host when you order. For payment and health integrations, register your own server's address.

Where you meet APIs

  • Phone apps fetching weather, messages and maps from their servers.
  • Online checkouts, where the shop calls a payment company's API to charge a card.
  • "Sign in with …" buttons, which share a limited profile with another site.
  • Budgeting apps that show balances from several banks, where the bank offers an API for it.
  • Parcel tracking on a shop's page, fed by the courier's API.
  • AI features inside other products, which send your prompt to a language model through its API.

Common mistakes

  • Ignoring the status code. Reading the body of a 401 or 429 as data gives empty or wrong results.
  • Retrying a POST blindly. It can create a second order or payment; use an idempotency key if offered.
  • Hard-coding the key. It spreads to repositories, screenshots and chat messages.
  • Hammering on a 429. Instant retries keep you over the limit; wait for the reset time.
  • Reading the wrong docs. Fields and limits change between versions; read the docs for the version you call.

Decision guide

Your needWhat to do
Try an API for the first timecurl -i against a public test API
Let users connect their accountOAuth, with the fewest scopes
Hear about events at onceA webhook instead of polling
Stay within limitsRead the rate-limit headers
Call an API that allowlists IPsRegister one fixed IP
Store a keyEnvironment variable or secrets manager

Frequently asked questions

What does API stand for?

API stands for application programming interface: the set of requests one program offers to others, with the rules for what each request must contain and what it returns. On the web, the word usually means an HTTP API that answers in JSON.

What is an API call?

An API call is a single request a program sends to an API, together with its response. GET /todos/1, for example, asks for one record, and the server answers with a status code such as 200 OK and the record in JSON. Paid APIs often bill per call.

What is an API endpoint?

An endpoint is the address of one operation, made of the API's base URL and a path, such as https://api.example.com/v1/orders. The same path can do different things by method: GET lists orders, POST creates one.

Is using an API free?

It depends on the provider. Some APIs need no key at all, many are free up to a quota and then charge per call, and some are open only to customers or partners. The price, the limits and what you may do with the data are on the provider's own pages.

What is an API gateway?

An API gateway is a server in front of one or more APIs that handles shared jobs first: checking keys, applying rate limits, routing each path to the right service and logging. The caller sees one address, with many services behind it.

Do I need to know how to code to use an API?

Not to try one. You can call a public API with curl or a documentation site's "try it" panel, and no-code automation tools connect APIs through forms. Building one into your own product takes code, often only a few dozen lines.

Summary

An API is a fixed set of requests one program can send to another: a method and an endpoint go out with a key or token, and a status code and data, usually JSON, come back. REST is the most common style; GraphQL, gRPC and webhooks cover flexible queries, internal services and event notices. Keep keys out of code and URLs, read the status code before the data, and when an API accepts calls only from registered addresses, give it one fixed IP to trust.

Ask ChatGPTAsk Claude