What Is an API and How It Connects Systems

You open a weather app on your phone. It shows temperature, humidity, a five-day forecast. That app doesn't own a satellite or process meteorological data — it asks another service for that information. The question is: how does it ask? The answer is an API.

That example beats the textbook definition because it makes something clear: an API isn't a standalone product. It's the bridge between two systems that need to exchange information without knowing each other's internals.

What an API actually is

API stands for Application Programming Interface. A name that explains everything and helps almost nobody.

A more useful definition: an API is a contract. It says: "send me a request in this format, and I'll send back a response in this format." What happens internally to process your request is my problem — you don't need to know.

Same principle as a TV remote. You press "volume up" and the sound increases. You don't understand the circuit board inside the TV — you just need to know which button to press and what to expect in return.

In software, APIs let systems built by different companies, in different languages, running on different servers, communicate as if they were parts of the same application.

Request and response: the basic unit of communication

Every API interaction runs in request/response cycles:

1. A system sends a request to the API
2. The API processes it
3. The API sends back a response with the result

For web APIs — the most common kind today — the transport layer is HTTP, the same protocol your browser uses to load websites.

An HTTP request has a few essential parts:

• Method: what you want to do (GET, POST, PUT, DELETE)
• URL: where you're sending the request
• Headers: metadata about the request (content type, authentication, etc.)
• Body (optional): the data you're sending

A response has a similar structure:

• Status code: a number indicating the outcome (200 OK, 404 Not Found, 500 Internal Server Error)
• Headers: metadata about the response
• Body: the data you got back

GET https://api.openweathermap.org/data/2.5/weather?q=New+York

This request uses the GET method (fetch data), points to a specific endpoint, and passes the city name as a query parameter. The API responds with a JSON payload containing temperature, conditions, humidity — exactly what the weather app renders on screen.

Endpoints: the access points of an API

An endpoint is a specific URL that exposes a piece of functionality. It's literally where you knock to ask for something.

An e-commerce API might have endpoints like:

GET    /products           → list all products
GET    /products/42        → return product with id 42
POST   /products           → create a new product
PUT    /products/42        → update product 42
DELETE /products/42        → delete product 42

Notice that the same resource (/products) behaves differently depending on the HTTP method used. This is the core of REST — more on that below.

Each endpoint is designed to do one thing well. You don't send a GET /products expecting it to also create a product — there's a separate endpoint for that, using POST.

JSON: the format that took over

When an API returns data, it needs a format the requesting system can read. The dominant format today is JSON — JavaScript Object Notation.

Despite the name, JSON has nothing to do with JavaScript exclusively. Any modern system can read and write it. It's plain text, structured, human-readable:

{
  "city": "New York",
  "temperature": 68.2,
  "unit": "fahrenheit",
  "conditions": "partly cloudy",
  "forecast": [
    { "day": "monday", "high": 72, "low": 58 },
    { "day": "tuesday", "high": 75, "low": 61 }
  ]
}

Each field has a key (string) and a value, which can be text, number, boolean, array, or another object. Nested structures let you represent complex data cleanly.

Before JSON, XML was the standard — more verbose, harder to parse. If you've ever seen a SOAP API from a legacy banking system, you know the difference firsthand.

REST: the style everyone uses (and few define correctly)

When someone says "REST API" or "RESTful API," they're describing an architectural style — not a protocol, not a specification. REST (Representational State Transfer) is a set of conventions for building HTTP APIs.

The main ones:

Resources and URLs: each URL represents a resource (/users, /orders/123, /products). Not /getUsers or /createProduct — actions go in the HTTP method, not the URL.

HTTP methods with meaning: GET fetches without modifying, POST creates, PUT/PATCH updates, DELETE removes. Using GET to delete data is a disaster waiting to happen — especially when there's a cache layer involved.

Stateless: each request contains everything the API needs to process it. The server doesn't maintain session state between requests. Authentication goes in each request's header, not in "you were logged in from the previous request."

Representation: the client receives a representation of the resource, not the resource itself. You request /users/42 and get a JSON object with the user's data — the API decides the response format.

REST isn't a formal specification, so two "REST APIs" can have quite different conventions. In practice, most of what we call REST today is better described as "JSON over HTTP with reasonable URLs."

Status codes: where to look first when something breaks

When a request fails, the response status code is the first place to check. They're organized in ranges:

• 2xx: success. 200 OK, 201 Created, 204 No Content.
• 3xx: redirection. The resource moved.
• 4xx: client error. You sent something wrong. 400 Bad Request (malformed request), 401 Unauthorized (missing authentication), 403 Forbidden (authenticated but no permission), 404 Not Found (resource doesn't exist).
• 5xx: server error. The problem is on the API's side. 500 Internal Server Error, 503 Service Unavailable.

The 4xx vs 5xx distinction matters: 4xx means you need to fix the request; 5xx means you need to wait or contact support.

{
  "error": "invalid_request",
  "message": "The 'email' field is required",
  "status": 400
}

When I'm integrating a new API, I keep the HTTP Status Codes tool open alongside the docs — useful for confirming what each code means when the documentation is vague.

A real example, step by step

Here's what happens when a food delivery app loads a restaurant menu:

1. The app sends a request:

GET /restaurants/123/menu
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

2. The API verifies the auth token, fetches data from the database, builds the response.

3. The API returns:

{
  "restaurant_id": 123,
  "name": "Napolitana Pizza",
  "menu": [
    {
      "id": 1,
      "name": "Margherita",
      "price": 14.99,
      "available": true
    },
    {
      "id": 2,
      "name": "Pepperoni",
      "price": 16.99,
      "available": false
    }
  ]
}

4. The app receives the JSON, renders the items on screen, shows "unavailable" for the Pepperoni.

No HTML, no CSS — just data. The app decides how to present it. The API decides how to store and process it. That separation of concerns is what lets the same backend power an iOS app, an Android app, and a web application simultaneously.

Frequently asked questions

What is API authentication?

Before processing any request, most APIs verify who's asking. The most common approaches: API Key (a secret string sent in the header or query string), Bearer Token (a JWT or session token in the Authorization header), and OAuth 2.0 (for delegated authorization — the "Sign in with Google" you use on other apps).

Without authentication, anyone could use your API quota, access data that isn't theirs, or run destructive operations.

Is REST the only way to build APIs?

No. GraphQL is a popular alternative where the client defines exactly which fields it wants in the response — useful when flexibility matters and REST's overfetching is a real problem. gRPC is another option, based on Protocol Buffers, common in microservice communication for being more compact and efficient than JSON. SOAP still exists in legacy systems, especially in banking and government.

What is rate limiting?

APIs typically limit how many requests you can make within a time window. Exceed the limit and you get 429 Too Many Requests. Rate limiting protects the API's infrastructure from abuse and ensures availability for all consumers. When integrating an external API, read the rate limit docs before you start building.

Public API vs. private API: what's the difference?

A public API is accessible by any developer (sometimes requiring registration and an API key). Examples: Stripe, OpenWeather, the Twitter API. A private API is used internally — the company's own frontend talking to its own backend. A partner API sits in between: accessible to specific business partners, with defined access agreements.

An API is a contract, not magic

APIs are one of the simplest ideas in modern computing — and one of the most powerful precisely because of that simplicity. A clear contract between systems lets teams work independently, services scale separately, and companies sell access to their capabilities as a product.

If you're just starting to work with APIs, the three things that will come up constantly: understanding what each endpoint does, reading response status codes when something fails, and checking the documentation before assuming the data format. The rest is practice.