Spring with Kotorin --4 REST API design

Overview / Description

In Spring with Kotorin --3. Omitting curly braces from function, API that can be accessed by GET / POST / PUT / DELETE method for RestController Added.

However, there was no particular guideline on how to add it, and it was added appropriately. Therefore, only the guideline to make the API to be published easy to understand was defined by giving a name to each function defined as follows.

@GetMapping(value = ["/display"])
fun getMessages() : List<Message> {

Therefore, I would like to change it to a ** REST API-like ** design.

Assumptions / Environment

Runtime version

Spring Dependencies

Development environment

Procedure / Explanation

REST API design

Here, we will not consider the API design strictly yet, but consider only the minimum policy.

Access URI

-** Access with noun ** --Not a verb

In the original definition, the root path was determined by annotation to the class, and the access URI was determined for each function. The name there was a verb notation for easy operation.

@RequestMapping("/simple")
class SimpleController {

    @GetMapping(value = ["/display"])
    fun getMessages() : List<Message> {

Therefore, in reality, the access was as follows, and the access was verb-like.

http://xxx/simple/display

What I wanted to * display * in this process was ** messages **. Therefore, change the access from the above to the access with the intended noun that targets * messages * as shown below.

http://xxx/messages

@RequestMapping("/messages")
class SimpleController {

    @GetMapping()
    fun getMessages() : List<Message> {

The access URL described in the function is gone, which will be explained next.

HTTP methods and CRUD operations

I tried to access by noun with the access URI explained above. Make sure that the CRUD operations (CREATE / READ / UPDATE / DELETE) on the noun you access are represented by HTTP methods (GET / POST / PUT / DELETE). As a result, you no longer need a per-function access URI as defined earlier.

The relationship between HTTP methods and CRUD operations is as follows.

HTTP method CRUD operation meaning
GET READ Get
POST CREATE Registration
PUT UPDATE update
DELETE DELETE Delete
POST / PUT --Idempotent

Both POST and PUT are HTTP methods used to create and update states. So why did POST be CREATE and PUT UPDATE?

The reason is the idempotency of HTTP methods.

Idempotence is a property that gives the same result even if it is re-executed.

The idempotency of the HTTP method is as follows.

HTTP method Idempotent
GET Idempotent
POST Non-idempotent
PUT Idempotent
DELETE Idempotent

Imagine the registration process. If you execute the same instruction multiple times, you will end up with the same record multiple times. It is not idempotent. On the other hand, in the update process, the result does not change even if the same instruction is executed multiple times. Idempotent.

Thinking this way, ** POST = CREATE = non-idempotent ** / ** PUT = UPDATE = idempotent ** is appropriate.

REST API fix

Based on the above, it has been modified as follows.

--Noun access --CRUD processing with HTTP method --Registration process considering idempotency

Before correction


@RequestMapping("/simple")
class SimpleController {

    @PutMapping(value = ["/insert"])
    fun insertMessage(@RequestBody message: Message) : Message {}

    @PostMapping(value = ["/update"])
    fun updateMessage(@RequestBody message: Message) : Message {}

Revised


@RequestMapping("/messages")
class SimpleController {

    @PostMapping
    fun insertMessage(@RequestBody message: Message) : Message {}

    @PutMapping
    fun updateMessage(@RequestBody message: Message) : Message {}

Summary / Looking back

This time, I touched on "easy" about the design of REST API. Strictly speaking, this is not enough. There are still many things to consider, such as API versioning, layering, collection representations and status codes.

For the time being, this time I treated it as the minimum thing to think simply and make.

In the future, I would like to reconsider API design when talking about the design of Microservices.

This source

Recommended Posts

Spring with Kotorin --4 REST API design
Spring with Kotorin --- 5. Actuator
Spring with Kotorin ―― 1. SPRING INITIALIZR
Spring with Kotorin --8 Repository layer
Spring with Kotorin --6 Asynchronous processing
Spring with Kotorin ―― 7. Service layer
REST API testing with REST Assured
Link API with Spring + Vue.js
Hello World (REST API) with Apache Camel + Spring Boot 2
[Spring Boot] Get user information with Rest API (beginner)
Implement a simple Rest API with Spring Security with Spring Boot 2.0
Customize REST API error response with Spring Boot (Part 2)
Customize REST API error response with Spring Boot (Part 1)
REST API test with REST Assured Part 2
Implement REST API with Spring Boot and JPA (Application Layer)
Implement REST API with Spring Boot and JPA (Infrastructure layer)
Spring with Kotorin --9 Database migration --Flyway
Implement REST API in Spring Boot
Implement REST API with Spring Boot and JPA (domain layer)
Implement a simple Rest API with Spring Security & JWT with Spring Boot 2.0
Implement a simple Web REST API server with Spring Boot + MySQL
[Beginner] Let's write REST API of Todo application with Spring Boot
Spring with Kotorin --2 RestController and Data Class
Build REST API with Apache2 + Passenger + Sinatra.
Configure microservices with Spring Cloud (4): API Gateway
Spring with Kotorin --8 Repository layer --Supplement: H2 Database
Create a web api server with spring boot
Compatible with Android 10 (API 29)
I created an api domain with Spring Framework. Part 2
Automatically map DTOs to entities with Spring Boot API
Spring with Kotorin --3. Omitting curly braces from the function
A memorandum when creating a REST service with Spring Boot
Self-made Validation with Spring
I created an api domain with Spring Framework. Part 1
Introduce swagger-ui to REST API implemented in Spring Boot
With Kotorin ―― 7. Scoping Function
Download with Spring Boot
Let's find out how to receive in Request Body with REST API of Spring Boot
Handle Java 8 date and time API with Thymeleaf with Spring Boot
Let's make a simple API with EC2 + RDS + Spring boot ①
Try hitting the zip code search API with Spring Boot
What I was addicted to with the Redmine REST API
Generate barcode with Spring Boot
Hello World with Spring Boot
Java Config with Spring MVC
Create XML-RPC API with Wicket
Test Web API with junit
Implement GraphQL with Spring Boot
Get started with Spring boot
Use Bulk API with RestHighLevelClient
Hello World with Spring Boot!
Run LIFF with Spring Boot
API creation with Rails + GraphQL
SNS login with Spring Boot
File upload with Spring Boot
Spring Boot starting with copy
Login function with Spring Security
Introduction to EHRbase 2-REST API
Using Mapper with Java (Spring)
Spring Boot starting with Docker
Hello World with Spring Boot