What is an API?

The restaurant analogy

The clearest way to explain an API: imagine a restaurant.

• You are the client (your app)
• The kitchen is the server (the service with the data or capability)
• The menu and waiter are the API, the defined set of requests you can make and the format of what will come back

You do not need to know how the kitchen works. You just need to know the menu (what requests are possible) and what will arrive (the response format). You order in the required format, and the kitchen responds predictably.

An API defines: what you can ask for, how to ask for it, what you will get back, and what errors look like. More: Introduction to web APIs, MDN

What an API request looks like

Most web APIs communicate using HTTP. A request has:

• A method: what kind of action (GET = read, POST = create, PUT/PATCH = update, DELETE = remove)
• A URL: what resource you are working with (/users/42, /orders, /forecasts)
• Headers: metadata including authentication (Authorization: Bearer your-api-key)
• A body: data you are sending (for POST and PUT requests)

A request to a weather API:

GET https://api.openweathermap.org/data/2.5/weather?q=Vienna&units=metric&appid=your-api-key

The response comes back as JSON (JavaScript Object Notation), a structured text format that almost every language can read:

{
  "name": "Vienna",
  "main": {
    "temp": 22.4,
    "humidity": 58
  },
  "weather": [
    { "description": "scattered clouds" }
  ]
}

Your code reads this JSON and displays or processes the data however you need.

HTTP status codes

The response always includes a status code that tells you what happened:

Learning to read status codes makes debugging much faster. A 401 means check your API key. A 429 means add a delay between requests. A 500 means the problem is on the API side, not yours.

REST vs GraphQL

REST is the dominant API style. Different URLs represent different resources (/users, /products/42). The method (GET/POST/PUT/DELETE) tells the server what to do with that resource. Responses contain everything in that resource, you ask for a user and you get everything about them.

GraphQL (developed by Facebook, open-sourced 2015) takes a different approach. You send a single query describing exactly what fields you want:

query {
  user(id: "42") {
    name
    email
    orders {
      id
      total
    }
  }
}

GraphQL gives you precisely what you ask for, nothing more. Useful when you have many different clients (mobile, web, desktop) that need different data shapes. More complex to implement than REST.

For beginners: assume REST. Most APIs you will use are REST. More: REST, MDN

API keys and authentication

Most commercial APIs require an API key, a secret string that identifies who is making the request. Without it, the API rejects your request (401 Unauthorized).

Critical rule: never put API keys in code that is committed to a public repository. Store them in:

• A .env file locally (listed in .gitignore)
• Your hosting platform’s environment variable settings
• A secrets manager in production (AWS Secrets Manager, 1Password, etc.)

If you accidentally expose a key, go to the provider’s dashboard and rotate (regenerate) it immediately.

Beyond API keys, some APIs use OAuth, a protocol that lets users grant your app access to their data without sharing their password (this is how “Log in with Google” works). More: OAuth 2.0, oauth.net

Rate limits

APIs almost always have rate limits, a maximum number of requests per minute or day. Exceeding them returns a 429 error. Rate limits exist to prevent abuse and manage infrastructure costs.

If you are building something that calls an API frequently (polling for updates, batch processing data), design with rate limits in mind: add delays, cache responses, and batch requests where possible.

Webhooks: the reverse of an API call

Instead of your code polling an API (“has anything changed?”), a webhook is a URL on your server that an external service calls when something happens.

You want to know when a Stripe payment succeeds. Instead of calling Stripe’s API every minute to check, you register a webhook URL: POST https://your-app.com/webhooks/stripe. When a payment completes, Stripe sends a POST request to that URL with the payment data.

Webhooks are event-driven and more efficient than polling for real-time data.

APIs you already interact with

Modern app development is largely: connect the right APIs, handle their responses, add your own logic in between.

How to explore and test APIs

Before writing code, test an API manually:

• Postman , desktop app for making API requests, inspecting responses, saving collections
• Insomnia , open-source alternative to Postman
• HTTPie , command-line HTTP client
• cURL, built into every terminal: curl -H "Authorization: Bearer key" https://api.example.com/data

Many APIs publish interactive documentation (Swagger / OpenAPI) where you can make test requests directly in the browser. Public APIs collection lists hundreds of free APIs to experiment with.

Further reading

• Introduction to Web APIs, MDN
• HTTP methods, MDN
• HTTP status codes, MDN
• Postman Learning Centre , from API basics to testing and automation
• Public APIs, community-maintained list , hundreds of free APIs to try
• REST API Tutorial , deeper guide to REST conventions
• OAuth 2.0 simplified , how login-with-X authentication works

What’s next

Next: What is a Database? , where the data that APIs serve actually lives.