What Is an API? A Beginner's Explanation

An API (Application Programming Interface) is a defined way for one piece of software to use another. It says: "send me a request shaped like this, and I will answer with a response shaped like that." The word covers everything from the functions a library exposes to the URLs a web service listens on, but when people say "the API" today they usually mean a web API.

A weather app on your phone does not contain weather data. It calls a weather service's API, sends a location, and gets back a small JSON document with the forecast. The app never needs to know how the forecast was made.

How a web API call works

A web API call is an ordinary HTTP request, the same mechanism your browser uses to load pages:

1. The client (an app, a script, a browser) sends a request to a URL such as https://api.example.com/users/42, with a method that says what it wants: GET to read, POST to create, PUT/PATCH to update, DELETE to remove.
2. The request can carry headers (for example an Authorization header with a token) and a body (data to create or update, usually JSON).
3. The server checks who is asking, does the work, and answers with a status code (200 OK, 404 not found, 401 not authorised, 500 server error) plus a body, again usually JSON.

GET /users/42 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOi...

HTTP/1.1 200 OK
Content-Type: application/json

{ "id": 42, "name": "Aarav", "plan": "free" }

The token in the Authorization header is often a JWT, three Base64-encoded parts that describe who the caller is. You can inspect one with the JWT decoder.

Why APIs matter

• Reuse. A payment provider builds a payment system once; thousands of shops use it through its API instead of building their own.
• Separation. The team that runs the database and the team that builds the phone app work independently, as long as both respect the API contract.
• Automation. Anything with an API can be scripted: deploying servers, sending email, posting to social media, generating invoices.

Reading API documentation

Good documentation lists, for each endpoint: the URL and method, required headers, the parameters and body fields, an example response, and the possible error codes. Two habits make learning a new API fast:

• Try the example request exactly as documented before changing anything.
• Paste the response into a JSON formatter to see its structure clearly, then generate types from it with the JSON to TypeScript tool if you are writing code against it.

Related concepts

• HTTP is the protocol beneath web APIs; status codes and headers come from it.
• REST, GraphQL and gRPC are different API styles. REST uses URLs per resource, GraphQL uses one endpoint with a query language, gRPC uses binary messages for speed.
• Rate limiting caps how many calls you can make per minute; a 429 status means you hit the cap.
• Webhooks are APIs in reverse: the service calls a URL you provide when something happens.