Detailed Explanation of Restful API

RESTful API (Representational State Transfer Application Programming Interface) is a design style used to build network-based application programming interfaces (APIs). It is based on a set of principles and conventions designed to enable different computer systems to communicate with each other and exchange data through the HTTP protocol.

Photo by micheile henderson on Unsplash

The history of the RESTful architectural style can be traced back to 2000 when it was first proposed by Roy Fielding in his doctoral thesis “Architectural Styles and the Design of Network-based Software Architectures”. In his paper, he describes the concept of REST (Representational State Transfer) and introduces a set of principles and conventions for designing and building distributed network applications.

The following are the main historical development stages of the RESTful architectural style:

1. Doctoral thesis (2000): Roy Fielding first proposed the concept of REST in his doctoral thesis. He emphasized the importance of resources in distributed system design and the use of unified interfaces and state transfer to achieve system scalability, performance, and extensibility.
2. Web 2.0 era (mid 2000s): As the Web evolved, REST started to gain more attention. Many Web 2.0 applications adopt a RESTful architecture, enabling them to exchange data and communicate with clients more efficiently.
3. The rise of mobile apps (2010s): With the rise of smartphones and mobile apps, RESTful APIs became the primary way to connect mobile clients to back-end services. Many social media, e-commerce, and other types of applications are adopting RESTful architectures.
4. Microservice architecture (late 2010s to present): RESTful APIs are also widely used in microservice architecture. Microservices architecture improves maintainability and scalability by splitting applications into small, independent services, and RESTful APIs become a standard way of communicating between these services.

Photo by micheile henderson on Unsplash

RESTful API

The summary of RESTful API is as follows:

1. Resources and Identifiers: In a RESTful API, each resource has a unique identifier (URI) that uniquely identifies that resource. Resources can be actual objects, data, services, etc.
2. Unified interface: RESTful API uses unified HTTP methods (GET, POST, PUT, DELETE, etc.) to perform operations such as obtaining resources, creating resources, updating resources, and deleting resources.
3. State-independent: RESTful APIs are stateless, and each request should contain enough information to understand and handle the request without maintaining session state.
4. Caching: RESTful APIs support caching, which can improve performance and reduce network traffic.
5. Client-Server: The RESTful API decouples the client and server so that they can be developed and extended independently.
6. Layered system: The RESTful API supports a layered system architecture, where each layer can be modified and optimized independently, increasing the flexibility and scalability of the system.
7. On-demand code: The server can deliver code to the client when needed to expand functionality.
8. Resource Oriented: RESTful API design should be centered around resources, not operations.
9. Self-describing messages: The request and response messages of a RESTful API should be self-describing so that developers can understand their meaning.

The core of RESTful APIs is the use of HTTP methods to perform operations on resources. The HTTP methods GET, POST, PUT, and DELETE are used to represent the four basic CRUD operations: create, read, update, and delete. This can be summarized as follows:

Parameter Passing

There are no mandatory provisions for parameter passing in the REST API specification, but there are some excellent experiences summarized from engineering practice. The commonly used parameter passing methods are as follows:

1. URL path parameters: Include parameters directly in the URL path. This is typically used to identify a unique identifier for a resource, such as to obtain information about a specific user.
   Example: GET /users/{id}
2. Query string parameters: Include parameters in the URL as part of the query string. This is used to pass filtering conditions and pagination information.
   Example: GET /users?role=admin&page=1&limit=10
3. Request body parameters: Include parameters in the request body, usually used when creating or updating resources. Data is usually sent in JSON or XML format.
   Example: POST /users， request body：{“username”: “john”, “email”: “john@example.com”}
PUT /users/{id}, request body: {“email”: “newemail@example.com”}

Restful API in Spring Boot

Spring MVC provides annotations for the four most common HTTP methods: GET, POST, PUT, and DELETE. These annotations can be used to easily implement RESTful APIs.

The only thing you need to pay attention to is passing parameters. For example, to get a resource, you would use the @GetMapping annotation and specify the URI of the resource in the annotation. To create a resource, you would use the @PostMapping annotation and specify the URI of the resource in the annotation.

Here is an example of how to use the @GetMapping annotation to get a resource:

@GetMapping("/user/{id}")
public ResponseEntity<User> getUserById(@PathVariable Long id) {
    // Query user information based on id and return
}

If there are too many parameters, they can be placed in the body of the HTTP message:

@PostMapping("/user")
public ResponseEntity<User> createUser(@RequestBody User user) {
    // Create a user and return the created user information
}

The REST API specification recommends giving a standardized response code to indicate the success or failure of an operation. This helps to make REST APIs more consistent and predictable.

Spring Boot provides the ResponseEntity class to build a response. The ResponseEntity class has a number of properties that can be used to set the status code, header information, and response body.

@GetMapping("/user/{id}")
public ResponseEntity<User> getUserById(@PathVariable Long id) {
    User user = userService.getUserById(id);
    if (user != null) {
        return ResponseEntity.ok(user);
    } else {
        return ResponseEntity.notFound().build();
    }
}