🍑 REST & RESTful API

🍑 REST API

🍑 REST API is an interface based on the principles of the REST.

REST (Representational State Transfer) is an architecture that was specifically designed to better employ the HTTP protocol.

Representational refers to the server-side resources represented in URI (Uniform Resource Identifier) combined with HTTP methods representing CRUD (Create, Read, Update, Delete) and its status codes. While State Transfer refers to the communication of resource states between the client and the server.

Hence, REST standardises the representation and transfer of resources through URIs, HTTP methods, and stateless interactions, making it highly scalable and easy to integrate across different platforms.

REST has the following characteristics or principles:

• 🍞 Uniform Interface

  • an architectural style where the operations on resources specified by a URI are performed in a standardised and limited interface.

  • implies that all API requests for the same resource should yield an identical outcome.

• 💻 Client - Server Architecture

  • same Client - Server model from the HTTP protocol.

  • the client concerns the UI and the server concerns the data processing, security, and etc.

• 💨 Stateless

  • identical stateless from the HTTP protocol.

  • a server does not maintain a state information leading REST API to be scalable.

• 📦 Cacheable

  • identical cacheable feature in the HTTP protocol.

  • contributes to the high performances from caching.

• 🎨 Self-Descriptive

  • allows REST API messages to be easily understood just by reading it.

• 🌊 Layered system

  • extra hierarchical layers can be implemented

  • a Load Balancer or a proxy server are good examples.

---

🧱 REST API Design Guide

Designing a REST API can be largely summarised into two key elements:

1. ℁ An URI should represent the available informational resources.

2. ✊ An action upon resources should be represented in the HTTP methods (GET, POST, PUT/PATCH, DELETE)

where the key principles combined with collections that underlie the layered URI architecture can be represented as underneath:

Hence, a request based on the REST API is advised not to contain any actions on the URI where the actions should be represented with the HTTP methods.

The below GET /members/delete/1 therefore can be replaced by DELETE /members/1.

REST API Request 1

GET /members/delete/1  -> DELETE /members/1

In practice, however, the above REST API rule can be hardly maintained once the represented resources over the URI become too complicated and vast in volume. This happens to be an exceptional cases where the URI may contain any action words:

REST API Request 2

GET : /users/{userid}/likes/devices 

---

🍓 RESTful API

🍓 RESTful contains all attributes from REST and contains further contains HATEOAS (Hypermedia as the engine of application state ).

HATEOAS means that when a client receives a response from the server, the response includes information about the next possible actions the client can take.

HATEOAS allows the client to understand what actions to take based solely on the server's response. It makes the communication between the client and the server more flexible.

This characteristic of RESTful services significantly improves the scalability and maintainability of web services. This is because the client and server can evolve independently.

Underneath could be a mock RESTful response where it contains HATEOAS as a part of its response:

RESTful API Response (JSON)

{
  "id": 123,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "status": "active",
  "_links": {
    "self": {
      "href": "/api/v1/users/123"
    },
    "update": {
      "href": "/api/v1/users/123",
      "method": "PUT"
    },
    "delete": {
      "href": "/api/v1/users/123",
      "method": "DELETE"
    },
    "orders": {
      "href": "/api/v1/users/123/orders",
      "method": "GET"
    }
  }
}

📚 References

IBM
Microsoft
Postman
F-Lab