What Is an API? A Beginner's Guide With Real Examples (REST, JSON and API Keys)

You check the weather on your phone, pay online with a card, log in with Google or watch a delivery driver move on a map. Behind every one of those experiences, software is quietly asking other software for help. The thing that makes this possible is the API.

If you have ever wondered what developers mean when they say "just call the API", this guide explains it clearly, with examples you can try yourself.

Key takeaways

• An API (Application Programming Interface) is a set of rules that lets one program request data or actions from another.
• Most web APIs use HTTP requests and JSON responses.
• REST is the most common API style; GraphQL and webhooks are popular alternatives.
• Protect APIs with authentication, HTTPS, validation and rate limits.

API explained with an analogy

Imagine a restaurant. You sit at a table with a menu. You do not walk into the kitchen to cook. Instead you tell the waiter what you want, the waiter carries the order to the kitchen, and later brings back your food.

• You are the client (your app or browser).
• The waiter is the API.
• The kitchen is the server and database.
• The menu is the API documentation: what you can ask for and how.

The API hides complexity and enforces rules, such as what you may order and in what format.

Real-world API examples

• Weather apps do not own weather stations; they call a weather API and display the results.
• "Sign in with Google" uses an authentication API so you do not create yet another password.
• Online checkout sends your payment details to a payment API such as Stripe or PayPal.
• Maps in a delivery app come from a mapping API.
• Booking sites check airline or hotel availability through partner APIs.
• Your own website may have a front end that fetches products, posts or users from your back-end API.

How a web API request works

Most web APIs follow the same pattern:

1. The client sends an HTTP request to a URL called an endpoint.
2. The request includes a method (what to do), optional headers (such as your API key), and sometimes a body (data you send).
3. The server processes the request.
4. The server returns a response with a status code and usually JSON data.

Common HTTP methods

Common status codes

• 200 OK: success.
• 201 Created: a new resource was created.
• 400 Bad Request: the request was invalid.
• 401 Unauthorized: you need to authenticate.
• 403 Forbidden: authenticated, but not allowed.
• 404 Not Found: the resource does not exist.
• 429 Too Many Requests: you hit a rate limit.
• 500 Server Error: something failed on the server.

What is JSON?

JSON (JavaScript Object Notation) is the standard text format for sending data between systems. It is readable by both people and machines:

{
  "id": 12,
  "title": "What is an API?",
  "tags": ["api", "beginners"],
  "published": true
}

Need to clean up messy data? Try our free JSON formatter.

Types of APIs

By audience

• Public (open) APIs: available to any developer, often with a free tier.
• Partner APIs: shared with specific business partners.
• Private (internal) APIs: used inside a company to connect its own systems.

By style

• REST: resources identified by URLs, standard HTTP methods, usually JSON. The most widely used.
• GraphQL: the client asks for exactly the fields it needs in a single request.
• SOAP: an older XML-based style still found in banking and enterprise systems.
• Webhooks: instead of you asking repeatedly, the server calls your URL when something happens, such as a payment completing.
• WebSockets: persistent connections for real-time features such as chat.

Try your first API call

You can call many public APIs right from your browser address bar or a tool such as curl. For example, a typical request looks like this:

curl https://api.example.com/v1/products?limit=3 \
  -H "Authorization: Bearer YOUR_API_KEY"

And in JavaScript:

const res = await fetch("https://api.example.com/v1/products?limit=3", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
const data = await res.json();
console.log(data);

Try it with a free, key-less public API, read the documentation, and print the result. Seeing real data come back is the moment APIs click.

Authentication and API keys

Most APIs need to know who is calling:

• API keys: simple secret strings; good for server-to-server use.
• OAuth 2.0: lets users grant limited access without sharing passwords (the "Sign in with..." flow).
• JWT (JSON Web Tokens): signed tokens carrying identity and permissions. Inspect them with our JWT decoder.

Golden rule: never put secret keys in front-end code, public repositories or screenshots. Store them in environment variables on the server.

API security basics

• Use HTTPS always.
• Authenticate and authorise every request; check what each user may do.
• Validate input to prevent injection and bad data.
• Rate limit to stop abuse and accidental overload.
• Return minimal data and avoid leaking internal errors.
• Log and monitor unusual activity.
• Version your API (for example /api/v1) so changes do not break clients.

Why APIs matter for businesses

• Integration: connect your website, CRM, accounting, shipping and payment tools without manual copy-paste.
• Automation: trigger workflows automatically; see our guide to workflow automation ROI.
• Speed of development: use ready-made capabilities (payments, maps, messaging) instead of building from scratch.
• New products: expose your own API to partners and customers.
• Multi-platform growth: one API can serve a website, mobile app and partner integrations. This is why we recommend an API-first approach when planning a web or mobile app.

Good API design habits

• Use clear, plural nouns for resources (/customers, /orders).
• Use proper HTTP methods and status codes.
• Support pagination, filtering and sorting for lists.
• Keep consistent error messages.
• Write documentation with examples; tools such as OpenAPI and Swagger help.

Anatomy of an API request, line by line

Here is a complete request to create a new customer, broken down:

POST /api/v1/customers HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json

{
  "name": "Rahim Uddin",
  "email": "rahim@example.com"
}

• POST /api/v1/customers: the method and the path of the resource.
• Host: which server receives the request.
• Authorization: proof of who is calling.
• Content-Type: tells the server the body is JSON.
• Body: the data to create.

The server might reply:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "c_8f2d1",
  "name": "Rahim Uddin",
  "email": "rahim@example.com",
  "createdAt": "2026-10-01T09:30:00Z"
}

Pagination, filtering and sorting

Lists can contain thousands of items, so APIs return them in pages and let you narrow results:

GET /api/v1/posts?page=2&limit=10&category=seo&sort=latest

Well-designed responses include metadata such as the total number of items and pages, so clients know when to stop.

Common API errors and what they mean

Webhooks: when the server calls you

Instead of asking "has the payment finished?" every few seconds, you give the provider a URL and they notify you. Best practices when receiving webhooks:

1. Verify the signature so you know the call really came from the provider.
2. Respond quickly with a 200 status and process the work in the background.
3. Handle duplicates safely, because providers may retry.
4. Log every event for troubleshooting.

Tools for working with APIs

• curl for quick requests from the command line.
• Postman, Insomnia or Bruno for exploring and saving requests.
• Browser DevTools, Network tab to watch the calls any website makes.
• OpenAPI and Swagger for documenting and testing APIs.
• Our free tools: JSON formatter, JWT decoder and Base64 encode and decode.

Learn more or build one

Next, try calling a public API, then build a tiny one with Node.js and Express or NestJS. If you want a professional API or integration for your business, our custom software team designs secure, well-documented APIs. Get in touch to discuss your project.