What is an API? A Plain-English Guide for Developers

BY TOOLS.FUN · MARCH 28, 2026 · 7 min read

An API — Application Programming Interface — is a contract between two pieces of software. It defines what requests you can make, what format to send them in, and what response you'll get back. Understanding APIs is arguably the single most important skill in modern software development, because nearly every application you build will consume or expose one.

The Restaurant Analogy

The most common way to explain an API: you're a customer in a restaurant. You don't go into the kitchen and cook your own food. Instead, you look at a menu, place an order with the waiter, and receive your meal. The menu is the API specification. The waiter is the API endpoint. The kitchen is the server. You never need to know how the kitchen works — only what you can order and what you'll receive.

What an API Actually Does

An API sits in front of a system and exposes specific, controlled functionality. A weather service's API might let you request the current temperature for a city. A payment processor's API might let you charge a credit card. A database API might let you query and insert records. In every case, the API hides the complexity of the underlying system and presents a clean interface.

Key insight: APIs are about defining a contract. The client and server agree on the format of requests and responses — usually documented in an OpenAPI (Swagger) spec — and both sides honour that contract independently.

REST APIs: The Dominant Style

REST (Representational State Transfer) is the most common API style on the web today. REST APIs use HTTP as the transport layer and rely on standard HTTP methods to express intent:

GET /users — retrieve a list of users
GET /users/42 — retrieve user with ID 42
POST /users — create a new user
PUT /users/42 — replace user 42
PATCH /users/42 — partially update user 42
DELETE /users/42 — delete user 42

REST responses are almost always JSON. A GET /users/42 response might look like: {"id": 42, "name": "Alice", "email": "[email protected]"}. Use our JSON Formatter to inspect and validate JSON API responses.

GraphQL: Ask for Exactly What You Need

GraphQL is a query language for APIs developed by Facebook. Instead of multiple endpoints for different resources, GraphQL has a single endpoint and lets the client specify exactly which fields it wants. This eliminates over-fetching (getting more data than you need) and under-fetching (needing multiple requests to get all the data).

A GraphQL query looks like: { user(id: 42) { name email posts { title } } }. The response contains exactly those fields — nothing more, nothing less.

REST vs GraphQL: REST is simpler to understand and cache at the HTTP layer. GraphQL is more efficient for complex frontends that need to combine data from multiple resources. Most public APIs are REST; GraphQL is popular in mobile apps and dashboards where bandwidth efficiency matters.

gRPC: High-Performance Service-to-Service APIs

gRPC is a high-performance RPC (Remote Procedure Call) framework from Google that uses Protocol Buffers (protobuf) as its serialisation format instead of JSON. It's typically used for internal microservice communication where performance matters more than human readability. gRPC is strongly typed, auto-generates client code in multiple languages, and supports streaming.

API Authentication

Most APIs require authentication to control access. Common methods include:

API Keys — a secret string passed in a header (X-API-Key: your-key) or query parameter. Simple but coarse-grained.
Bearer Tokens (JWT) — a signed JSON Web Token passed in the Authorization: Bearer <token> header. Contains claims about the user.
OAuth 2.0 — a delegation protocol where users grant third-party apps access to their data without sharing passwords.
HTTP Basic Auth — username and password Base64-encoded in the Authorization header. Use our Base64 tool to encode credentials.

HTTP Status Codes

APIs communicate success and failure through HTTP status codes:

2xx Success: 200 OK, 201 Created, 204 No Content
3xx Redirection: 301 Moved Permanently, 302 Found
4xx Client Error: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Too Many Requests
5xx Server Error: 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable

Debug tip: a 401 means you're not authenticated at all. A 403 means you're authenticated but lack permission. Many developers confuse these two.

Making Your First API Call

The fastest way to call any API is with curl on the command line. Use our cURL Converter to build and understand cURL commands interactively. A basic GET request: curl https://api.example.com/users. A POST with JSON body: curl -X POST -H "Content-Type: application/json" -d '{"name":"Alice"}' https://api.example.com/users.

API Rate Limiting

Most public APIs enforce rate limits — a cap on how many requests you can make per minute or hour. When you exceed the limit, the API returns a 429 status code. Good API clients implement exponential backoff: retry after 1 second, then 2 seconds, then 4 seconds, doubling each time with some jitter added.

Rate limit headers: look for X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After headers in API responses. Use our Timestamp Converter to convert the Unix epoch reset time to a human-readable datetime.

← Back