REST Overview - REST API, HTTP Methods and HTTP Status Codes

Representational State Transfer (REST) is a widely used architectural style for designing networked applications, particularly web services. REST emphasizes a stateless, client-server architecture that maximizes the scalability, performance, and simplicity of the service. In this blog post, we will provide an overview of REST, including what it is, the basics of REST APIs, HTTP methods and status codes, REST architectural constraints, and the advantages of using REST.

What is REST?

REST, or Representational State Transfer, is an architectural style defined by Roy Fielding in his doctoral dissertation in 2000. It is based on a set of principles and constraints that make web services scalable, flexible, and easy to maintain. 

In simple words, the REST stands for REpresentational State Transfer. 

-State means data

-REpresentational means formats (such as XML, JSON, YAML, HTML, etc)

-Transfer means carrying data between consumer and provider using HTTP protocol

RESTful systems typically use HTTP as the communication protocol and leverage standard HTTP methods to perform operations on resources.

What is a REST API?

A REST API (Application Programming Interface) is an API that adheres to the principles and constraints of REST. It allows clients to interact with server resources using standard HTTP methods. Each resource in a REST API is identified by a unique URL, and clients can perform operations on these resources using HTTP methods.

Key Concepts of REST API

• Resources: These are the objects or representations of data that the API exposes. Each resource is identified by a URI (Uniform Resource Identifier).
• Representations: The data format in which resources are retrieved or sent, typically JSON or XML.
• Stateless Interactions: Each request from the client to the server must contain all the information needed to understand and process the request, making each interaction independent of others.

HTTP Methods and HTTP Status Codes

HTTP Methods

• GET: Retrieve a resource or a list of resources.
  • Example: GET /users retrieves a list of users.
• POST: Create a new resource.
  • Example: POST /users creates a new user.
  • Request Body:

    {
      "name": "John Doe",
      "email": "john.doe@example.com"
    }
    

• PUT: Update an existing resource or create it if it does not exist.
  • Example: PUT /users/1 updates the user with ID 1.
  • Request Body:

    {
      "name": "John Doe",
      "email": "john.doe@example.com"
    }
    

• DELETE: Delete a resource.
  • Example: DELETE /users/1 deletes the user with ID 1.
• PATCH: Partially update a resource.
  • Example: PATCH /users/1 updates part of the user data with ID 1.
  • Request Body:

    {
      "email": "john.newemail@example.com"
    }
    

HTTP Status Codes

• 200 OK: The request was successful.
  • Example: A successful GET request returning a list of users.
• 201 Created: A new resource was successfully created.
  • Example: A POST request creating a new user.
• 204 No Content: The request was successful, but there is no content to send in the response.
  • Example: A successful DELETE request.
• 400 Bad Request: The server could not understand the request due to invalid syntax.
  • Example: A POST request with missing required fields.
• 401 Unauthorized: The client must authenticate itself to get the requested response.
  • Example: A request to a protected resource without proper authentication.
• 403 Forbidden: The client does not have access rights to the content.
  • Example: A request to access a resource without sufficient permissions.
• 404 Not Found: The server cannot find the requested resource.
  • Example: A GET request for a user ID that does not exist.
• 500 Internal Server Error: The server has encountered a situation it doesn't know how to handle.
  • Example: An unexpected error on the server side.

REST Architectural Constraints

1. Client-Server

Description: The client-server constraint separates the user interface (client) from the data storage and processing (server). This separation allows clients and servers to evolve independently, enhancing scalability and flexibility.

Benefits:

• Simplifies the client by handling data storage and business logic on the server.
• Allows for the independent development and deployment of client and server.

Example: In a social media application, the client (web or mobile app) requests user data from the server, which handles data retrieval, processing, and storage.

2. Stateless

Description: The stateless constraint ensures that each client request contains all the information needed to process it. The server does not store any client context between requests, making each request independent.

Benefits:

• It simplifies server design as it does not need to maintain the session state.
• Enhances scalability by allowing the server to handle more requests without storing client-specific data.

Example: When a user requests their profile data, the request includes all necessary authentication information. The server processes the request without needing to remember previous interactions.

3. Cacheable

Description: Server responses should be explicitly marked as cacheable or non-cacheable. This allows clients and intermediaries to cache responses, reducing the load on the server and improving performance.

Benefits:

• Reduces server load by caching frequently accessed resources.
• Improves response times for clients by serving cached data.

Example: A news website API can mark the list of latest articles as cacheable for a few minutes. Subsequent requests within this period are served from the cache, reducing server load.

4. Uniform Interface

Description: The uniform interface constraint ensures that a standard method of communication is used across the API, simplifying and decoupling the architecture. This includes:

• Resource identification through URIs.
• Manipulation of resources through representations (e.g., JSON, XML).
• Self-descriptive messages.
• Hypermedia as the engine of application state (HATEOAS).

Benefits:

• Simplifies interactions between clients and servers.
• Enhances visibility and consistency across the API.

Example: Using standard HTTP methods like GET, POST, PUT, and DELETE to perform CRUD operations on resources such as /users or /posts.

5. Layered System

Description: The layered system constraint allows an architecture to be composed of hierarchical layers. Each layer has a specific function, and components in one layer cannot see beyond the immediate layer they interact with.

Benefits:

• Enhances scalability by enabling load balancing and shared caching.
• Improves security by isolating layers and controlling access.

Example: A web application can use a load balancer to distribute requests across multiple servers, with caching servers in between to store frequently accessed data.

6. Code On Demand (Optional)

Description: The code-on-demand constraint allows servers to extend client functionality by sending executable code (e.g., JavaScript) to clients. This is the only optional constraint in REST.

Benefits:

• Enhances client capabilities without requiring updates to the client application.
• Reduces the need for pre-installed software on the client side.

Example: A web page can request a script from the server to dynamically update its content without requiring a full page reload.

Advantages of REST

• Simplicity: Uses standard HTTP methods and status codes, making it easy to understand and use.
• Scalability: Stateless nature allows easy scaling by adding more servers.
• Flexibility: Can handle multiple types of calls and return different data formats.
• Performance: Can leverage caching to improve performance and reduce server load.
• Modifiability: Client and server can evolve independently, enabling easy updates and extensions.
• Portability: Standard protocols and data formats make APIs accessible from various devices and platforms.

Additional Resources

• Learn how to develop REST APIs using the Jersey framework: Jersey RESTful Tutorial
• Learn how to develop REST APIs using JAX-RS with the RESTEasy framework: RESTEasy CRUD Example Tutorial

By understanding the basics of REST and how to implement RESTful APIs, you can design and develop web services that are scalable, efficient, and easy to maintain. Explore the additional resources provided to deepen your knowledge and skills in creating RESTful APIs.