HTTP - REST

REST is a set of rules and recommendations for designing a web API.

On this page

REST (Representational State Transfer) is the most common way for applications and services to talk to each other over the Internet. If you’ve ever used a mobile app that fetches data from a server, you’ve likely interacted with a REST API.

Think of REST as a set of “best practices” or “guidelines” for creating web services. A service that follows these rules is called RESTful.

REST is NOT a Protocol

Unlike HTTP, REST is not a strict protocol or a standard. It’s an architectural style. This means it’s a collection of useful recommendations that help you build services that are easy to use and scale.

The Core Concept: Resources

In the world of REST, everything is a resource.

A resource is any piece of data that your API provides.

For example:

  • A user
  • A book
  • A list of tasks
  • A weather report

Each resource is identified by a unique address called a URI (Uniform Resource Identifier), which usually looks like a URL.

Six REST Principles

To make a service truly RESTful, it should follow these six principles. Don’t worry if they sound a bit technical at first—they are mostly about keeping things simple and organized.

  1. Client-Server Model: The user interface (client) and the data storage (server) are separate. This allows them to evolve independently.
  2. Statelessness: The server doesn’t remember anything about previous requests. Every request must contain all the information needed to understand it.

    Think of it like a vending machine: it doesn’t care who you are; it just needs the right coin and a button press to give you a soda.

  3. Cacheable: Responses should define themselves as cacheable or not to prevent clients from requesting the same data over and over.
  4. Uniform Interface: This is the most important part. All resources should be accessed in a consistent way, making the API easy to learn.
  5. Layered System: A client shouldn’t need to know if it’s talking directly to the server or to an intermediary (like a security layer or a load balancer).
  6. Code on Demand (Optional): Sometimes the server can send executable code (like a script) to the client. This is rarely used.

HTTP Methods: The “Verbs” of REST

REST usually works on top of HTTP. It uses HTTP “methods” to tell the server what action to perform on a resource.

This is very similar to the CRUD model used in databases:

ActionHTTP MethodCRUD Equivalent
ReadGETRetrieve data
CreatePOSTAdd new data
UpdatePUTReplace/Update data
DeleteDELETERemove data

How they work in practice:

  • GET: Used to read a resource. If successful, the server returns the data (usually in JSON format) and a 200 OK status.
  • POST: Used to create a new resource. If successful, it returns a 201 Created status and the link to the new item.
  • PUT: Used to update an existing resource or create it if you know the ID. Returns 200 OK or 204 No Content.
  • DELETE: Used to remove a resource. Returns 200 OK or 204 No Content.

Example: A Library API

Imagine we are building an API for a library. Here is how we would use REST to manage books:

GoalMethodURI
Get all booksGEThttps://api.example.com/books
Get a specific bookGEThttps://api.example.com/books/123
Add a new bookPOSThttps://api.example.com/books
Update book #123PUThttps://api.example.com/books/123
Delete book #123DELETEhttps://api.example.com/books/123

API Naming Conventions

To make your API “intuitive” (easy for other developers to guess how it works), follow these naming rules:

1. Use Nouns, Not Verbs

The URI should represent the “thing” (the resource), not the “action”. The action is already defined by the HTTP method.

  • ✅ Correct: GET /users
  • ❌ Incorrect: GET /getUsers or POST /create-user

2. Use Plural Nouns

It’s standard practice to use plurals for collections.

  • ✅ Correct: /books/12
  • ❌ Incorrect: /book/12

3. Use Hyphens for Readability

If a resource name has multiple words, use hyphens (-), not underscores (_) or camelCase.

  • ✅ Correct: /product-categories
  • ❌ Incorrect: /product_categories or /productCategories

4. No Trailing Slashes

Don’t add a / at the end of your URI. It’s redundant and can sometimes cause confusion for caches.

  • ✅ Correct: /items
  • ❌ Incorrect: /items/

5. Version Your API

Always include a version number (like v1) in the path. This allows you to make big changes later without breaking older apps that still use your API.

  • ✅ Example: https://api.example.com/v1/users

6. Filtering and Sorting

Use “query parameters” (the part after the ?) to filter or sort lists.

  • ✅ Example: /items?color=red&sort=price