Using Correct Status Codes in Responses

Tutorial 2 of 5

Introduction

This tutorial aims to guide you on how to correctly use HTTP status codes in your responses when building REST APIs. By the end of this tutorial, you will gain a deeper understanding of the common HTTP status codes, their usage, and their importance in the process of creating more robust and meaningful applications.

Prerequisites:
- Basic understanding of REST APIs
- Familiarity with a programming language, preferably JavaScript
- Basic knowledge of HTTP/HTTPS protocols

Step-by-Step Guide

HTTP status codes are three-digit numbers that are returned by servers to indicate the status of a requested resource. They are grouped into five classes:

Informational responses (100–199)
Successful responses (200–299)
Redirection messages (300–399)
Client error responses (400–499)
Server error responses (500–599)

Let's dive into the most commonly used status codes in each class:

200 OK: This is the most common code, indicating a successful GET, PUT, PATCH, or DELETE request.
201 Created: This indicates that a resource was successfully created in response to a POST request.
400 Bad Request: The request was malformed. This could be caused by various actions by the user such as providing invalid JSON data in the request body.
401 Unauthorized: The user is not authorized to access the resource. This is often used when authentication is required and has failed or has not yet been provided.
404 Not Found: The requested resource could not be found.
500 Internal Server Error: This indicates an unexpected server issue.

Code Examples

Let's assume we are using Express.js to create our REST API.

1. Example of 200 OK

app.get('/users', (req, res) => {
  const users = getAllUsers(); // Assume this function returns all users
  res.status(200).json(users);
});

Here, res.status(200).json(users) sends a response with status code 200 and JSON data of users.

2. Example of 201 Created

app.post('/users', (req, res) => {
  const newUser = createUser(req.body); // Assume this function creates a new user
  res.status(201).json(newUser);
});

In this case, res.status(201).json(newUser) sends a response with status code 201 and JSON data of the newly created user.

Summary

In this tutorial, we have covered the importance of using correct status codes in our REST APIs. We have also looked into some common status codes and their meanings. Next, you might want to learn more about the remaining HTTP status codes and when to use them. Here are some additional resources:

Practice Exercises

Exercise 1: Create an endpoint that returns a 404 Not Found status code when the requested resource is not found.

Exercise 2: Create an endpoint that returns a 401 Unauthorized status code when the user is not authenticated.

Exercise 3: Update the user creation endpoint to return a 400 Bad Request status code when the request body is missing required fields.

Remember, practice makes perfect. Happy coding!