In this post, we will look at what is a RESTful service or REST API and the characteristics that define it. Also, we will go over the HTTP methods that can be used to expose the functionalities of the RESTful service through APIs.

What Is A RESTful Service or REST API?

REST is an acronym for Representational State Transfer which is coined by Roy Fielding in 2000 in his dissertation Architectural Styles and the Design of Network-based Software Architectures. REST is an architectural style that defined certain constraints for building a distributed system using the HTTP protocol.

RESTful service is any distributed system written in any language and exposes its functionalities over the HTTP protocol within the REST architectural style constraints. It’s a client-server architecture web service that presents resources through certain representations along with self-descriptive messages.

REST API – Client-Server Architecture
REST API – Client-Server Architecture

Characteristics of RESTful Service

Roy Fielding added specific constraints to the REST architecture to call any distributed system as RESTful service. We will discuss all those main constraints which make up the characteristics of the RESTful service in the below section.

Constraint 1: Client-Server

With the traditional web application, where the server renders the view components with the required data for each of the requests, this first and fore-most REST principle tries to decouple the user interface concerns from the data storage concerns with the client-server architecture style.

This separation of concerns principle makes the distributed system’s server components scalable by removing any view rendering related concerns while improving the user interface portable across multiple platforms. Thus, the same server components can be used by multiple clients on different platforms with various view specific implementation with the same response from the server.

Constraint 2: Stateless

This second constraint forces the server not to store any session related information for any request. It’s the client’s responsibility to store and manage any session related information at the client-side and send all the information related to request to the server so that server doesn’t need to use any of the previous request details or any stored session details at the server side to serve the current request.

This constraint provides the RESTful service with visibility, reliability, and scalability. We will see how these properties are available to the server components in the client-server architecture with REST principles applied.

  1. Visibility: Since each request contains all the information need to process it and respond with the required information, the server does not need to look beyond the single request to understand it’s nature. Thus, the visibility of the server is improving.
  2. Reliability: If any particular request is failed at the server-side, the server-side components will not be impacted as any other further requests do not depend on the previous requests. Thus, the reliability of the RESTful service is improved because then it can still serve the requests even after any partial failures previously.
  3. Scalability: It is improved because the server component doesn’t need to store any information between the requests, it can quickly free-up the resources once any request is processed and responded. Also, these characteristics simplify the RESTful service’s implementation as it does not have to manage any resource usage across requests.

Having a trade-off just like any architectural choice is inevitable even though stateless constraint provides several benefits to the RESTful service,  Since the server does not maintain a shared context across the requests, the network performance is reduced for repetitive data sent in for a series of requests.

Constraint 3: Cache

To improve the reduced network performance introduced by the previous constraint, a new constraint Cache is added to the REST architecture. With this constraint, the server component can label the data in the response for a request as cacheable or non-cacheable. When the client receives the cacheable response, it can re-use this response for the same request later.

This ability to cache the response at the client-side improves the network efficiency, scalability, and user-perceived performance by reducing the number calls to fetch the response for the same request repeatedly.

Constraint 4: Uniform Interface

The main feature that distinguishes the REST architecture from other web architectures is the Uniform Interface constraint. This constraint enforces the component’s behavior or interfaces to be uniform across all the components even though the implementation varies.

REST has been defined with below four interface related constraints to provide the uniform interface across its components.

  1. Resource: It’s the critical abstraction of information in REST. A resource can be any information that can be named: a document, image or temporal service, a collection of other resources a non-virtual object and so on. Also, a resource is a conceptual mapping to a set of entities. A resource must be identified by a resource identifier, URL or URN.
  2. Representation: The resources are manipulated by the REST components using the representation to capture the current or modified state of the resource. The representation consists of data and metadata about the data. The data format of representation is known as a media type.
  3. Self-Descriptive Message: The response from the server should contain the media type for the resource’s representation to the client. So that the client knows how to parse and process the data it received for any request.
  4. HATEOAS: It’s the acronym for Hypermedia As The Engine Of Application State. It means that once the client receives the response from the server, the response should have links for other application states so that the client can use those links to move to the next state of the application.

RESTful Service Operations

We use RESTful service to perform below four principal operations on the resources that it exposes. These are called CRUD operations.

  1. Create: With this operation, a new resource is created.
  2. Read: To retrieve the representation of the resource we use the read operation of the RESTful service.
  3. Update: Once the resource is created, we can modify the resource details with the update operation.
  4. Delete: If an existing resource to be removed from the RESTful system, the delete operation is used.

HTTP Methods

Since the RESTful service is built upon HTTP protocol for external communication, in this section, we will see how the API endpoints are accessed via the HTTP verbs/methods for different functionalities. Also, how the RESTful service’s CRUD operations are initiated with the appropriate HTTP methods.

POST Method

The create operation is performed when a request is sent with the POST HTTP method. New resource representation should be sent as a request body to create it in the REST system.

REST API HTTP PORT Method Interaction
REST API HTTP POST Method Interaction

Example:

curl --request POST 
  --url http://localhost:3000/customers 
  --header 'Content-Type: application/json' 
  --data '{
  "firstName": "John",
  "lastName": "Smith",
  "email": "john.smith@example.com",
  "phoneNumber": "9876543210",
  "address": "100 E Street",
  "city": "New York",
  "state": "NY",
  "zipCode": "10000",
  "country": "USA"
}'

GET Method

To fetch the existing resource’s representation, the request needs to be sent with the GET HTTP method. The response would be containing the resource’s representation with additional metadata along with the media type of the response.

REST API HTTP GET Method Interaction
REST API HTTP GET Method Interaction

Example:

curl --request GET \
--url http://localhost:3000/customers
curl --request GET \
--url http://localhost:3000/customers/5b19e5f017d1aa0e55ed8d96

PUT Method

To modify the existing resource, we can send a request with PUT HTTP method along with the new representation of the existing resource as the request body.

REST API HTTP PUT Method Interaction
REST API HTTP PUT Method Interaction

Example:

curl --request PUT 
  --url http://localhost:3000/customers/5b19e5f017d1aa0e55ed8d96 
  --header 'Content-Type: application/json' 
  --data '{
    "_id": "5b19e5f017d1aa0e55ed8d96",
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@example.com",
    "phoneNumber": 1234567890,
    "address": "401 W Street",
    "city": "New York",
    "state": "NY",
    "zipCode": "10000",
    "country": "USA",
    "__v": 0
}'

DELETE Method

To perform the delete operation on the existing resource, we have to use the DELETE HTTP method while sending the request to the RESTful service with the URL of the resource which needs to be removed from the system.

REST API HTTP DELETE Method Interaction
REST API HTTP DELETE Method Interaction

Example:

curl --request DELETE 
  --url http://localhost:3000/customers/5b19e5f017d1aa0e55ed8d96

Please check out the index page for this Node.js RESTful API development with TDD approach tutorial with all the posts in sequence in one place.

This blog post is an excerpt from the book Building Node.js REST API with TDD approach. Please check out the link for more information.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.