REST APIs

What Is a REST API?
Complete Beginner's Guide

// march 2026 · 10 min read

REST APIs power the entire modern web. Every time you check the weather on your phone, post a tweet, or load your Spotify playlist, a REST API is doing the heavy lifting in the background. But what actually IS a REST API, and how does it work?

This guide explains everything from zero — no prior experience needed.

// The Simple Explanation

An API (Application Programming Interface) is a way for two pieces of software to talk to each other. A REST API is a specific type of API that follows a set of rules called REST (Representational State Transfer).

Think of it like a restaurant. You (the client) sit at a table. You don't go into the kitchen — instead, you give your order to a waiter (the API). The waiter takes your request to the kitchen (the server), and brings back your food (the data). The REST API is the waiter.

    In technical terms: A REST API is an interface that lets clients (browsers, apps, other servers) send HTTP requests to a server and receive data back — usually in JSON format.
  

// How REST APIs Work

The Request-Response Cycle

Every REST API interaction follows the same pattern:

A client sends an HTTP request to a URL (called an endpoint)
The server processes the request
The server sends back an HTTP response with a status code and data

Client → GET https://api.example.com/users/123
Server → 200 OK + {"id": 123, "name": "Alex", "email": "alex@example.com"}

// HTTP Methods (The Verbs)

REST APIs use HTTP methods to indicate what action you want to perform. There are four main ones:

GET — Read Data

Retrieve information. Doesn't change anything on the server. Like asking "show me the menu."

GET /api/users          → returns list of all users
GET /api/users/42       → returns user with ID 42
GET /api/posts?limit=10 → returns first 10 posts

POST — Create Data

Send new data to the server to create a resource. Like submitting a form.

POST /api/users
Body: {"name": "Sam", "email": "sam@example.com"}
→ Creates new user, returns 201 Created

PUT — Update Data

Update an existing resource. Replaces the whole thing (unlike PATCH which only updates part of it).

PUT /api/users/42
Body: {"name": "Samuel", "email": "sam@example.com"}
→ Updates user 42

DELETE — Delete Data

Remove a resource from the server.

DELETE /api/users/42
→ Deletes user 42, returns 204 No Content

// HTTP Status Codes

Every API response includes a status code that tells you what happened:

200 OK — Request succeeded
201 Created — New resource was created
204 No Content — Succeeded but nothing to return
400 Bad Request — Your request had an error
401 Unauthorized — You need to authenticate
403 Forbidden — You don't have permission
404 Not Found — Resource doesn't exist
500 Internal Server Error — Something broke on the server

// JSON: The Language of REST APIs

Most REST APIs communicate using JSON (JavaScript Object Notation) — a lightweight, human-readable format for structuring data.

{
  "user": {
    "id": 42,
    "name": "Alex Johnson",
    "email": "alex@example.com",
    "created_at": "2026-01-15T10:30:00Z",
    "roles": ["admin", "editor"]
  }
}

JSON uses key-value pairs, arrays, and nested objects. Once you know JSON, you can read any REST API response.

// Your First API Call

Let's make a real API call right now. Open your browser's developer console (F12 → Console) and paste this:

fetch('https://api.coinbase.com/v2/prices/BTC-USD/spot')
  .then(r => r.json())
  .then(data => console.log(data))

This calls the Coinbase public API and gets the current Bitcoin price. No API key required. You just made your first REST API call.

// Using cURL from the Terminal

cURL is a command-line tool for making HTTP requests. It's the developer's Swiss Army knife for testing APIs:

curl https://api.coinbase.com/v2/prices/BTC-USD/spot

Add -i to see response headers, -X POST to change the method, and -d '{"key":"value"}' to send a request body.

// REST API Authentication

Most real-world APIs require authentication to know who you are and what you're allowed to do. Common methods:

API Keys

The simplest method. You get a secret key and include it in your request header or URL. Easy to implement but not the most secure.

GET /api/data
Headers: Authorization: Bearer your-api-key-here

OAuth 2.0

The standard for "Login with Google/GitHub/Twitter" flows. More complex but very secure. The API gives you a temporary access token after you authenticate.

JWT (JSON Web Tokens)

A self-contained token that encodes user information. Your client sends it with every request. Very common in modern applications.

// REST vs Other API Types

You'll also encounter these API styles:

GraphQL — You specify exactly what data you want. One endpoint, flexible queries. Used by GitHub, Shopify, Facebook.
gRPC — High-performance, uses Protocol Buffers instead of JSON. Common in microservices.
SOAP — Old enterprise standard using XML. Still used in banking and healthcare. Very verbose.
WebSockets — Persistent two-way connection for real-time data (chat, live prices, etc.).

REST is the most common by far because it's simple, stateless, and works everywhere HTTP works.

Pro tip: Use free public REST APIs to practice. OpenWeatherMap, CoinGecko, JSONPlaceholder, and the GitHub API all have free tiers perfect for learning.

// More Dev Guides

Deep dives on REST, sleep optimization, and developer productivity.

explore spunk.rest

What Is a REST API?Complete Beginner's Guide