# Everything about RESTful APIs

## What is REST?

REST is an **architectural style** used to design web services that allow clients and servers to exchange information over a network.  
  
REST stands for Representational State Transfer.  
  
Let's break that down.  
  
Re - **Representational** - A representation is the format in which a resource's information is sent from a server to a client.

Let's say the information stored is a student. When a client requests this student's information, the server can send a representation of the student in JSON format.

```python
{
  "id": 101,
  "name": "Rahul",
  "status": "Active"
}
```

The client receives this representation rather than directly accessing the server's database.  
  
S**tate** refers to the information or condition of a resource at a particular moment.  
  
Later, the student's status might change to `"Graduated"`.

The resource's state has changed, and a subsequent request can return a new representation reflecting that change.

**Transfer** means sending a resource's representation between a client and a server over a network.

## What is a RESTful API?

A RESTful API is an Application Programming Interface designed according to the principles of REST (Representational State Transfer).

## Principles of REST

REST follows six architectural principles that help developers build web APIs that are simple, scalable, and easy to maintain.

1.  Client-Server  
    The client handles the user interface, while the server manages data and business logic. Both can work independently.  
    **Example**: A shopping app displays products, while the server provides product information.
    
2.  Statelessness  
    Every request must contain the information needed to process it. The server does not depend on remembering previous requests.  
    **Example**: Each API request includes the necessary authentication credentials.
    
3.  Cacheability  
    Responses can be stored and reused when caching is permitted, reducing repeated requests and improving performance.  
    **Example**: A browser temporarily stores product information instead of requesting it every time.
    
4.  Uniform Interface  
    The API follows consistent rules for identifying and interacting with resources.  
    **Example**: GET /products/10 retrieves information about product 10.
    
5.  Layered System  
    The client can communicate with the server through intermediary components without needing to know the internal architecture.  
    **Example**: An API gateway checks requests before forwarding them to the server.
    
6.  Code on Demand (Optional)  
    The server can send executable code to the client to extend its functionality. This principle is optional.  
    **Example**: A server sends JavaScript that a browser can execute.
    

HTTP methods define the type of action a client wants to perform on a resource through an API. They help the server understand whether the client wants to retrieve, create, update, or delete data.

| Method | Purpose | Example |
| --- | --- | --- |
| GET | Retrieve data | View products |
| POST | Create a resource | Add a product |
| PUT | Create or replace a resource | Replace product details |
| PATCH | Partially update a resource | Change a product's price |
| DELETE | Remove a resource | Delete a product |

##   
REST API Endpoints  

An API endpoint is a specific URL through which a client can access a resource or interact with a server.

In a RESTful API, endpoints are used to access resources such as users, products, orders, or student records. The client sends an HTTP request to an endpoint, and the server processes the request and returns an appropriate response.

Eg.  
[https://api.example.com/products/10](https://api.example.com/products/10)  

| Component | Meaning |
| --- | --- |
| `https://` | The communication scheme |
| [`api.example.com`](http://api.example.com) | The server's domain |
| `/products` | The product resource collection |
| `/10` | Identifies a specific product |

## Types of REST API Endpoints

Collection endpoint

```plaintext
GET /products
```

Individual resource endpoint

```plaintext
GET /products/10
```

Related resource endpoint

```plaintext
GET /products/10/reviews
```

## Endpoints with Query Parameters

Sometimes a client needs specific results rather than an entire collection. Query parameters can help filter, sort, or paginate the results.

```plaintext
GET /products?sort=price&order=asc
```

###   
Best Practices for Designing REST API Endpoints

When designing endpoints, developers should follow a few common conventions:

*   Use nouns for resources: Prefer /products over /getProducts.
    
*   Use plural names consistently: For example, /users and /orders.
    
*   Use path parameters for specific resources: For example, /users/101.
    
*   Use query parameters for filtering: For example, /products?category=books.
    
*   Use HTTP methods for operations: Avoid putting action names such as /deleteProduct/10 into URLs when a resource-oriented endpoint with DELETE is more appropriate.
