REST

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:

Action	HTTP Method	CRUD Equivalent
Read	GET	Retrieve data
Create	POST	Add new data
Update	PUT	Replace/Update data
Delete	DELETE	Remove 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:

Goal	Method	URI
Get all books	GET	https://api.example.com/books
Get a specific book	GET	https://api.example.com/books/123
Add a new book	POST	https://api.example.com/books
Update book #123	PUT	https://api.example.com/books/123
Delete book #123	DELETE	https://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