New rule: entity creation endpoints with putmapping/postmapping without response status 201

[dgroup]

Summary

Key	Value
Rule	...
Ruleset	io/github/dgroup/arch4u/pmd/api/arch4u-rest-ruleset.xml
Category	Design
Framework	Spring
Since	0.2.0
Incidents in past at my experience	1

Rule definition

<rule name="MissingHttpResponseStatus"
      since="0.2.0"
      language="java"
      externalInfoUrl="https://github.com/dgroup/arch4u-pmd/discussions/..."
      message="Avoid endpoints for create action without HTTP response code 201 in case of success: https://github.com/dgroup/arch4u-pmd/discussions/..."
      class="io.github.dgroup.arch4u.pmd....">
    <priority>3</priority>
    <properties>
      <property name="annotations" value="org.springframework.web.bind.annotation.PutMapping|org.springframework.web.bind.annotation.PostMapping"/>
      <property name="responseCodes" value="org.springframework.http.HttpStatus.CREATED"/>
      <property name="methods" value="^create.+$"
    </properties>
</rule>

Why?

According to HTTP standard for response codes once entity successfully created the endpoint should return 201 response code.

@PutMapping("/employees/{id}") // violation as no response code
public ResponseEntity<Employee> create(@Valid @RequestBody Employee employee) {
     // ...
}

@ResponseStatus(HttpStatus.CREATED)
@PutMapping("/employees/{id}") // ok, response code is here
public ResponseEntity<Employee> create(@Valid @RequestBody Employee employee) {
     // ...
}

@PutMapping("/employees/{id}") // ok, as method has no 'creation' semantic
public ResponseEntity<Employee> processIt(@Valid @RequestBody Employee employee) {
     // ...
}

Read more

• https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/bind/annotation/ResponseStatus.html
• https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#2xx_success