Skip to main content

Everything about RESTful APIs

REST Explained: A Beginner's Guide to RESTful APIs

Updated 4 min readMarkdown
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.

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

The client receives this representation rather than directly accessing the server's database.

State 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

Component Meaning
https:// The communication scheme
api.example.com The server's domain
/products The product resource collection
/10 Identifies a specific product

Types of REST API Endpoints

Collection endpoint

GET /products

Individual resource endpoint

GET /products/10

Related resource endpoint

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.

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.

No comments yet. Be the first to comment.