Returning HTTP Status Codes: an overview
Why the default status codes (200 on success, 500 on any error) aren't enough, shown by a request for a category that doesn't exist and still gets 200.
Apprentice · Spring Boot · REST API · Updated
By default, the web methods of a @RestController return a status code of 200 when they have completed their work. If an error occurs, a status code of 500 is returned.
In the POST lesson, we added a @ResponseStatus annotation to the API methods that should return a different success status code.
@PostMapping(path="/api/categories")
@ResponseStatus(value = HttpStatus.CREATED)
public Category addCategory (@RequestBody Category category)
{
return categoryDao.insert(category);
}
However, this only addresses the status code that is returned if the method call is successful. If the method fails, i.e. if there is an error, the API call will return a status code of 500, or server error.
We want to have more fine-grained control over the status code returned by our methods.
Valid Request
A request for a category with a valid category ID - we would expect a status code of 200 - success.
GET http://localhost:8080/api/categories/8
@GetMapping(path="/api/categories/{id}")
public Category getCategoryById(@PathVariable int id)
{
//use the DAO to get the category by id
return categoryDao.getCategoryById(id);
}
The server would return:
HTTP/1.1 200
Content-Type: application/json
Transfer-Encoding: chunked
Date: Thu, 19 Sep 2024 14:11:33 GMT
{
"categoryId": 8,
"categoryName": "Seafood",
"description": "Seaweed and fish"
}
Invalid Request
But what if a user requests a category ID that does not exist?
Consider this request:
GET http://localhost:8080/api/categories/300
@GetMapping(path="/api/categories/{id}")
public Category getCategoryById(@PathVariable int id)
{
//use the DAO to get the category by id
return categoryDao.getCategoryById(id);
}
The API will still return status code 200 - success, but the DAO will have returned null so that the response body will be empty.
HTTP/1.1 200
Content-Length: 0
Date: Thu, 19 Sep 2024 14:07:38 GMT
We need finer control.
Do it: predict the status code Spring Boot sends
Before you take control of the status codes, it helps to know exactly what Spring Boot sends when you don't. Write a method that predicts it, from the two things that decide it: the method's @ResponseStatus annotation, if it has one, and whether the method threw an exception.
The method gets two values:
responseStatus: the code in the method's@ResponseStatusannotation, anint, such as201forHttpStatus.CREATED. It's0when the method has no@ResponseStatus.threw:truewhen the method threw an exception,falsewhen it finished its work.
For example, GET /api/categories/300: getCategoryById has no @ResponseStatus, and it doesn't throw (the DAO returns null, and the method returns it):
| Question | For GET /api/categories/300 |
|---|---|
| Did the method throw? | no |
Does it have a @ResponseStatus? |
no: 0 |
| The status sent | 200, even though there's no category 300 |
So defaultStatus(0, false) returns 200.
Your job: write the method defaultStatus(int responseStatus, boolean threw) so it returns the status code Spring Boot sends, an int.
- When the method threw, return
500, whatever its@ResponseStatussays: the annotation only covers success. - Otherwise, when it has a
@ResponseStatus(responseStatusisn't0), return that code. - Otherwise, return
200.
Practiced live on the lesson page: write the Java right there and check it.