What is a REST API?

What is a REST API?

Welcome to the REST API Tutorial! In this series you will build a complete RESTful API from scratch using Node.js, Express, and MongoDB — then connect it to a React front-end. But first, let us understand what a REST API actually is.

What Is an API?

An API (Application Programming Interface) is a set of rules that allows one piece of software to talk to another. APIs define the requests you can make, the data formats to use, and the responses you will get back.

Analogy	Explanation
Restaurant	You (client) give your order to a waiter (API) who takes it to the kitchen (server) and brings back your food (response)
TV Remote	You press buttons (API endpoints) to send commands to the TV (server) without knowing its internal circuitry

What Is REST?

REST (Representational State Transfer) is an architectural style for designing APIs. It was defined by Roy Fielding in 2000 and has become the standard approach for web APIs. A REST API uses standard HTTP methods to perform operations on resources identified by URLs.

REST Principles

Principle	Meaning
Client-Server	The client and server are separate — the client handles the UI, the server handles data and logic
Stateless	Each request contains all the information needed — the server does not remember previous requests
Uniform Interface	Resources are identified by URLs and manipulated through standard HTTP methods
Resource-Based	Everything is a resource (user, post, product) with a unique URL
JSON Format	Data is typically exchanged in JSON format (though XML is also possible)

Resources and Endpoints

In REST, everything is a resource — a user, a blog post, a product, an order. Each resource has a URL (called an endpoint) that identifies it:

GET    /api/users          → Get all users
GET    /api/users/123      → Get user with ID 123
POST   /api/users          → Create a new user
PUT    /api/users/123      → Update user 123
DELETE /api/users/123      → Delete user 123

HTTP Methods (CRUD)

HTTP Method	CRUD Operation	Purpose
GET	Read	Retrieve data from the server
POST	Create	Send new data to the server
PUT	Update	Replace existing data on the server
DELETE	Delete	Remove data from the server

CRUD stands for Create, Read, Update, Delete — the four basic operations you can perform on any data. REST maps these operations to HTTP methods.

Request and Response

CLIENT                                SERVER
  │                                      │
  │── GET /api/users ──────────────────→ │
  │                                      │  Looks up users in database
  │←── 200 OK ──────────────────────────│
  │    [{"id":1,"name":"Alice"},         │
  │     {"id":2,"name":"Bob"}]           │
  │                                      │
  │── POST /api/users ─────────────────→ │
  │   {"name":"Charlie","email":"..."}   │  Creates new user
  │←── 201 Created ─────────────────────│
  │    {"id":3,"name":"Charlie"}         │

HTTP Status Codes

Range	Category	Common Codes
2xx	Success	200 OK, 201 Created, 204 No Content
3xx	Redirection	301 Moved Permanently, 304 Not Modified
4xx	Client Error	400 Bad Request, 401 Unauthorized, 404 Not Found
5xx	Server Error	500 Internal Server Error, 503 Service Unavailable

JSON Format

{
    "id": 1,
    "name": "Alice",
    "email": "alice@example.com",
    "age": 28,
    "active": true
}

JSON (JavaScript Object Notation) is the standard data format for REST APIs. It is lightweight, human-readable, and natively supported by JavaScript.

Real-World API Examples

• Twitter API — fetch tweets, post tweets, follow users
• GitHub API — list repos, create issues, manage pull requests
• Stripe API — process payments, manage subscriptions
• Google Maps API — geocoding, directions, place search
• OpenWeather API — current weather, forecasts, historical data

What You Will Build

• A Node.js server with Express
• RESTful routes for CRUD operations
• MongoDB database with Mongoose schemas
• Error handling and validation
• GeoJSON support for location data
• A React front-end that consumes the API

Key Takeaways

• An API allows different software systems to communicate with each other
• REST is an architectural style that uses HTTP methods and URLs to manage resources
• Each resource has a unique endpoint (URL) and supports CRUD operations via GET, POST, PUT, DELETE
• REST APIs are stateless — each request is independent and self-contained
• Data is exchanged in JSON format and responses include HTTP status codes