What is an API? REST, HTTP Methods and JSON Explained for Beginners

The Restaurant Analogy

API stands for Application Programming Interface, and the jargon hides a simple idea. Think of a restaurant. You (the customer) don't walk into the kitchen and cook your own meal. You look at a menu — a fixed list of things you're allowed to order — tell the waiter what you want, and the kitchen prepares it and sends it back through the waiter.

An API is that menu-and-waiter system for software:

• You = an app (the weather app on your phone, a website, a script you wrote)
• The menu = the API documentation — the list of things you're allowed to ask for
• The waiter = the API itself, carrying requests in and responses out
• The kitchen = the servers and databases you never see and never need to understand

A Real Request, Step by Step

Here's what happens when you open a weather app and it shows today's temperature:

1. Your app builds a request: GET https://api.weather.com/v1/current?city=delhi — "give me the current weather for Delhi."
2. The request travels over HTTPS to the weather company's API server (the same protocol your browser uses, which is why networking fundamentals matter here).
3. The server validates it: Is the API key valid? Is the city name real? Is this app allowed to call this endpoint?
4. The server does the work: queries its database for Delhi's latest readings.
5. The server responds with a status code and structured data:

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

{
  "city": "Delhi",
  "temperature_c": 31,
  "condition": "clear",
  "humidity": 42,
  "updated": "2026-07-06T14:30:00Z"
}

Your app reads that data and paints it on screen as "31°C ☀️ Clear". The whole round trip usually takes under 200 milliseconds. Notice what your app didn't need: no access to the weather company's database, no knowledge of their code, no idea whether the kitchen runs on Linux or Windows. Just the menu.

HTTP Methods: The Verbs

Every API request uses an HTTP method — a verb that says what kind of action you want. Four cover almost everything:

This maps to the classic CRUD pattern from databases — Create, Read, Update, Delete. POST creates, GET reads, PUT updates, DELETE deletes. If you've read our Databases chapter, this should feel familiar: an API is very often just a safe, controlled front door to a database.

JSON: The Data Format

JSON (JavaScript Object Notation) is the format almost every modern API uses for its answers. It's plain text, human-readable, and built from just two structures:

• Objects — curly braces with key/value pairs: {"name": "Priya", "age": 24}
• Arrays — square brackets with lists: ["red", "green", "blue"]

Nest them and you can describe anything:

{
  "order_id": 8841,
  "status": "shipped",
  "items": [
    {"name": "USB-C cable", "qty": 2, "price_inr": 349},
    {"name": "NVMe SSD 1TB", "qty": 1, "price_inr": 4999}
  ],
  "delivery": {"city": "Mumbai", "eta_days": 2}
}

Despite the name, JSON has nothing to do with knowing JavaScript — every language (Python, PowerShell, C#, Java, Go) reads and writes it natively. When people say an API is "RESTful", they usually mean: it uses HTTP methods as verbs, URLs as nouns (/orders/8841), and JSON as the data format.

Status Codes: The Answer Signal

Every response starts with a three-digit code that tells you, at a glance, how the request went. The first digit is the category:

API Keys and Authentication

Most useful APIs need to know who is calling — to bill usage, enforce limits, and protect private data. The common mechanisms, simplest first:

API Keys

A long random string (like sk_live_9f8a7b...) you attach to every request, usually in a header. It identifies your app the way a membership card identifies you. Simple, and fine for server-to-server calls — but treat keys like passwords: never paste them into public code, chats, or GitHub repositories.

OAuth (Login with Google)

When an app offers "Sign in with Google", that's OAuth — a protocol where you approve a permission screen and the app receives a limited, expiring token instead of your password. The app never sees your Google password, and you can revoke its access anytime. Tokens with scopes ("read your email address, nothing else") are what make third-party integrations safe.

Rate Limits

APIs cap how many requests you can make (say, 100 per minute). Exceed it and you get 429 Too Many Requests. This protects the server from accidental floods and abuse — the same thinking you'll meet again in our Security chapter.

Types of APIs You'll Hear About

• REST — the dominant style described in this article: HTTP verbs, URL paths, JSON. Learn this first.
• GraphQL — one endpoint where the caller specifies exactly which fields it wants. Popular in modern web apps to avoid over-fetching.
• SOAP — an older, XML-heavy standard still common in banking, government, and legacy enterprise systems.
• WebSockets — a two-way, always-open connection for live data: chat apps, stock tickers, multiplayer games.
• Webhooks — a "reverse API": instead of you asking repeatedly, the server calls your URL when something happens (payment completed, code pushed). This is how services like payment gateways notify shops instantly.

Try It Yourself (No Coding Required)

You can call a real API right now. Paste this into your browser's address bar:

https://api.github.com/users/torvalds

You'll get live JSON describing Linus Torvalds' GitHub profile — followers, repos, join date. Your browser just acted as an API client, sent a GET request, and received a 200 OK with JSON. On Linux, macOS, or Windows you can do the same from a terminal:

curl https://api.github.com/users/torvalds

Congratulations — you've made your first API call. Everything else in this chapter is refinement of what you just did.

Key Takeaways

Learn More

APIs sit at the crossroads of several chapters:

• Networking — How Networks Talk — the HTTP and DNS plumbing every API call rides on
• Databases — where API data actually lives, and why CRUD maps to HTTP methods
• Security — authentication, tokens, and why leaked API keys cause breaches
• DevOps — deploying and monitoring the servers that host APIs