1. Understand the REST

REST is a full description of Representational State Transfer, which in Chinese means Representational State Transfer. It first appeared in 2000 in the doctoral dissertation of Roy Fielding, one of the main authors of the HTTP specification. It is important to note that REST does not have a clear standard, but rather a style of design. If an architecture conforms to REST constraints and principles, we call it a RESTful architecture. The REST architectural style is not theoretically tied to HTTP, but currently HTTP is the only instance that is relevant to REST.

1.1. The REST principles

  • Resources can be exposed through directory structure-style URIs
  • Representations can be passed through data objects or attributes expressed in JSON or XML
  • Messages use uniform HTTP methods (for example, GET, POST, PUT, and DELETE)
  • The interaction between a stateless client and a server is stateless between requests, and each request from the client to the server must contain the information necessary to understand the request

1.2. The HTTP method

Use HTTP to map CRUD (Create, Retrieve, Update, delete < Create, retrieve, update, delete – add, delete, modify and search >) operations to HTTP requests. If resources are exposed according to the semantics of the HTTP method, the interface will have security and idempotent features, such as GET and HEAD requests that are safe and do not change server state no matter how many times they are requested. While GET, HEAD, PUT, and DELETE requests are idempotent, the result is always the same no matter how many times the resource is operated on, and subsequent requests have no more impact than the first.

1.2.1. GET

  • Safe and idempotent
  • Access to information

1.2.2. POST

  • Unsafe and not idempotent
  • Perform operations using the entities provided in the request, which can be used to create or update resources

1.2.3. PUT

  • Unsafe but idempotent
  • Perform operations using the entities provided in the request, which can be used to create or update resources

1. DELETE

  • Unsafe but idempotent
  • Delete the resource

The difference between POST and PUT in creating a resource is whether the name (URI) of the resource being created is determined by the client. For example, to add a Java category to my blog post, the generated path is category name /categories/ Java, then use the PUT method. However, many people directly map POST, GET, PUT, and DELETE to CRUD, for example in a typical Rails RESTful application.

1.3. HTTP status code

The status code indicates the result of the HTTP request:

  • 1 xx: information
  • 2 xx: success
  • Xx: forward
  • 4XX: Client error
  • 5XX: Server error

1.4. Media types

Accept and Content-Type in the HTTP header can be used to describe what is sent or requested in an HTTP request. If the client requests a JSON response, you can set Accept to Application/JSON. Accordingly, if the Content being sent is XML, you can set the content-type to Application/XML.

2. REST API design best practices

Here are some best practices for designing REST apis, with the following in mind:

A URL is a sentence in which a resource is a noun and an HTTP method is a verb.

2.1. Use nouns to represent resources

Here are some examples:

  • GET – /users: Returns the user list
  • GET – /users/100: Returns a specific user
  • POST – /users: Creates a new user
  • PUT – /users/200: Updates a specific user
  • DELETE – /users/711: deletes a specific user

Don’t use verbs:

  • /getAllsers
  • /getUserById
  • /createNewUser
  • /updateUser
  • /deleteUser

2.2 Use appropriate serialization formats in HTTP headers

Both the client and the server need to know the format to use for communication, which is specified in the HTTP header:

  • Content-type Defines the request format
  • Accept defines a list of acceptable response formats

2.3 Get methods and query parameters should not change state

Use the PUT, POST, and DELETE methods to change the state, and do not use the GET method to change the state:

  • GET /users/711? activate 或
  • GET /users/711/activate

2.4. Use subresources to represent associations

If a resource is associated with another resource, use subresources:

  • GET /cars/711/drivers: Returns the list of drivers of car 711
  • GET /cars/711/drivers/4: Go back to the 4th driver of bus 711

2.5. Use appropriate HTTP methods (verb)

Just to remind you of this:

A URL is a sentence in which a resource is a noun and an HTTP method is a verb.

  • GET: Gets the representation specified in the URI resource, and the body of the response message contains the details of the requested resource.
  • POST: Creates a new resource specified by the URI and requests the body of the message to provide details of the new resource. Note that POST can also trigger actions that do not necessarily create new resources.
  • PUT: Creates or replaces a resource with a specified URI. The request message body specifies the resource to be created or updated.
  • DELETE: deletes the resource with the specified URI.

2.6. HTTP response status code

When a client makes a request to a server through the API, the client should know the feedback: failure, pass, or request error. HTTP status codes are a set of standardized codes that can be interpreted differently in different scenarios. The server should always return the correct status code. Here are the important HTTP code categories:

  • 2XX (Success classification) : These status codes request actions to be received and processed successfully by the server.
    • 200: Ok Indicates the standard status code of GET, PUT, or POST requests.
    • 201: Created indicates that an instance has been Created and is used for POST methods.
    • 204: No Content Indicates that the request was processed successfully but No Content is returned. Often used in DELETE method returns.
  • 3XX (Forwarding classification)
    • 304: Not Modified Indicates that the client has cached the response and does Not need to transfer the same content again.
  • 4XX (Client error classification) : These status codes represent that the client submitted an error request.
    • 400: Bad Request indicates that the client Request is not processed because the server cannot understand the client Request.
    • 401: Unauthorized A client is Unauthorized to access resources. The client should add the required authentication information and request the resources again.
    • 403: Forbidden Indicates that the request is valid and the client is authorized, but the client is not authorized to access the resource.
    • 404: Not Found Indicates that the requested resource is now unavailable.
    • 410: Gone indicates that the requested resource has been removed.
  • 5xx (Server misclassification)
    • 500: Internal Server Error indicates that the request is valid, but an exception occurs on the Server.
    • 503: Service Unavailable Indicates that the server is down or Unavailable, usually when the server is in maintenance state.

2.7. Name regulations

You can follow any name convention, as long as it is consistent across applications. If the request and response bodies are JSON types, follow the hump name convention.

2.8. Search, sorting, filtering, and paging

Some of the examples above are simple queries on a data set. For complex data, we need to add parameters to the GET method API to handle it. Here are some examples:

  • Sort: In this example, where the customer wants to GET a list of sorted companies, GET /companies should accept multiple sort parameters when querying. For example, GET/companies? Sort = rank_ASC will sort companies in ascending rank order.
  • Filtering: To filter the data set, we can pass different options through query parameters. Such as GET/companies? Category =banking&location= India Filter companies that are banks and located in India.
  • Search: The API endpoint for searching the company name in the company list should be GET /companies? Search = Digital.
  • Paging: When a data set is too large, we should split the data set into smaller chunks to improve server performance and make it easier for the client to handle the response. Such as GET/companies? Page =23 means to retrieve page 23 of the list of companies.

2.9. Restful API version

Generally, a simple number without dots is used to indicate the version number, and the letter V before the number indicates the version number, as shown below:

  • /blog/api/v1
  • Api.yourservice.com/v1/companie…

2.10. Handling JSON error bodies

API error handling mechanisms are important and should be well planned. It is highly recommended to always include an error message in the return field. A JSON error body should provide the developer with some useful information: error messages, error codes, and detailed descriptions. Here’s a good example:

{
    "code": 1234."message": "Something bad happened :("."description": "More details about the error here"
}
Copy the code

2.11. How do I create Rest API urls

The recommended URL format is:

  • HTTP (s) : / / {domain (: port number)} / {said the value of the REST API} / {API version} / {path} identify resources
  • HTTP (s) : / / {said REST API domain (: port number)} / {API version} / {path} identify resources

As follows:

  • Example.com/api/v1/memb…
  • Api.example.com/v1/members/…

3. Develop Restful Web services based on Spring Boot

Spring Boot provides excellent support for building RESTful Web services in enterprise applications.

3.1. Introduce dependencies

To build RESTful Web services, we need to add the Spring Boot Starter Web dependency to the build configuration file. For Maven users, add dependencies to the POM.xml file using the following code:

<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-web</artifactId>    
</dependency>
Copy the code

For Gradle users, add dependencies to the build. Gradle file using the following code:

compile('org.springframework.boot:spring-boot-starter-web')
Copy the code

3.2. Rest related notes

Before continuing to build RESTful Web services, it is recommended that you familiarize yourself with the following annotations:

Rest Controller

The @RestController annotation is used to define RESTful Web services. It provides JSON, XML, and custom responses. The syntax is as follows:

@RestController
public class ProductServiceController {}Copy the code

Request Mapping

The @requestMapping annotation is used to define the request URI to access the REST endpoint. We can define the Request method to consume the Produce object. The default request method is GET:

@RequestMapping(value = "/products")
public ResponseEntity<Object> getProducts(a) { }
Request Body
   @RequestBodyAnnotations are used to define the request body content type.public ResponseEntity<Object> createProduct(@RequestBody Product product) {}Copy the code

Path Variable

The @pathvariable annotation is used to define custom or dynamic request URIs. Path variable is enclosed in curly braces within the request URI, as shown below:

public ResponseEntity<Object> updateProduct(@PathVariable("id") String id) {}Copy the code

Request Parameter

The @requestParam annotation is used to read the request parameters from the request URL. This is a required parameter in the absence case, or you can set the default value for the request parameter, as shown below: public ResponseEntity getProduct( @RequestParam(value = “name”, required = false, defaultValue = “honey”) String name) { }

3.3. Write REST apis

GET API

The following sample code defines the HTTP GET request method. In this example, we use HashMap to store the Product. Notice that we use the POJO class to store the product. In this case, the request URI is /products, which returns the list of products from the HashMap repository. The following controller class file contains the REST endpoint for the GET method:

package com.tutorialspoint.demo.controller;

import java.util.HashMap;
import java.util.Map;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.tutorialspoint.demo.model.Product;

@RestController
public class ProductServiceController {
   private static Map<String, Product> productRepo = new HashMap<>();
   static {
      Product honey = new Product();
      honey.setId("1");
      honey.setName("Honey");
      productRepo.put(honey.getId(), honey);
      
      Product almond = new Product();
      almond.setId("2");
      almond.setName("Almond");
      productRepo.put(almond.getId(), almond);
   }
   @RequestMapping(value = "/products")
   public ResponseEntity<Object> getProduct(a) {
      return newResponseEntity<>(productRepo.values(), HttpStatus.OK); }}Copy the code

POST API

HTTP POST requests are used to create resources. This method contains the request body. We can define custom or dynamic urls by sending request parameters and path variables. The following sample code defines the HTTP POST request method. In this example, we use HashMap to store the Product, which is a POJO class. Here, the request URI is /products, which returns a string after the product is stored in the HashMap repository.

package com.tutorialspoint.demo.controller;

import java.util.HashMap;
import java.util.Map;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import com.tutorialspoint.demo.model.Product;

@RestController
public class ProductServiceController {
   private static Map<String, Product> productRepo = new HashMap<>();
   
   @RequestMapping(value = "/products", method = RequestMethod.POST)
   public ResponseEntity<Object> createProduct(@RequestBody Product product) {
      productRepo.put(product.getId(), product);
      return new ResponseEntity<>("Product is created successfully", HttpStatus.CREATED); }}Copy the code

PUT API

HTTP PUT requests are used to update existing resources. This method contains the request body. We can define custom or dynamic urls by sending request parameters and path variables. The following example shows how to define an HTTP PUT request method. In this example, we use HashMap to update the existing product. Here, the product is a POJO class. Here, the request URI is /products/{id}, which returns a string after the product is stored in the HashMap repository. Note that we use the path variable {id} to define the product ID to be updated:

package com.tutorialspoint.demo.controller;

import java.util.HashMap;
import java.util.Map;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import com.tutorialspoint.demo.model.Product;

@RestController
public class ProductServiceController {
   private static Map<String, Product> productRepo = new HashMap<>();
   
   @RequestMapping(value = "/products/{id}", method = RequestMethod.PUT)
   public ResponseEntity<Object> updateProduct(@PathVariable("id") String id, @RequestBody Product product) {
      productRepo.remove(id);
      product.setId(id);
      productRepo.put(id, product);
      return new ResponseEntity<>("Product is updated successsfully", HttpStatus.OK); }}Copy the code

DELETE API

HTTP Delete requests are used to Delete existing resources. This method does not contain any request body. We can define custom or dynamic urls by sending request parameters and path variables. The following example shows how to define the HTTP DELETE request method. In this example, we use a HashMap to remove the existing product, represented by a POJO. The request URI is /products/{id}, which returns a string after the product has been removed from the HashMap repository. We use the path variable {ID} to define the id of the product to be removed.

package com.tutorialspoint.demo.controller;

import java.util.HashMap;
import java.util.Map;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import com.tutorialspoint.demo.model.Product;

@RestController
public class ProductServiceController {
   private static Map<String, Product> productRepo = new HashMap<>();
   
   @RequestMapping(value = "/products/{id}", method = RequestMethod.DELETE)
   public ResponseEntity<Object> delete(@PathVariable("id") String id) {
      productRepo.remove(id);
      return new ResponseEntity<>("Product is deleted successsfully", HttpStatus.OK); }}Copy the code