A REST API is an interface that allows applications to communicate over HTTP using resources and standardized HTTP methods.

REST stands for Representational State Transfer. It is an architectural style for designing networked applications.

Imagine building an e-commerce application. You might have the following resources:

• Users
• Products
• Categories
• Orders
• Payments

Each resource can be exposed through an API endpoint.

For example:

GET /api/products

This endpoint retrieves products from the server.

POST /api/products

This endpoint creates a new product.

PUT /api/products/123

This endpoint replaces an existing product.

DELETE /api/products/123

This endpoint deletes a product.

The frontend does not need to know how the backend stores its data. It communicates with the backend through HTTP requests and receives responses, commonly in JSON format.

Where are REST APIs used?

• Web applications.
• Mobile applications.
• E-commerce platforms.
• Authentication systems.
• Admin dashboards.
• Payment integrations.
• Third-party service integrations.
• Microservices architectures.

In this tutorial, we will build a complete User Management REST API using Node.js, Express and MongoDB.

HTTP methods define the operation that a client wants to perform on a resource.

The most commonly used methods in REST API development are GET, POST, PUT, PATCH and DELETE.

GET retrieves information from the server.

Example:

GET /api/users

POST creates a new resource.

Example:

POST /api/users

PUT replaces an existing resource with a new representation.

Example:

PUT /api/users/123

PATCH partially updates an existing resource.

Example:

PATCH /api/users/123

DELETE removes a resource.

Example:

DELETE /api/users/123

Understanding the difference between PUT and PATCH is particularly important.

Suppose a user document contains:

{
  "name": "John",
  "email": "john@example.com",
  "age": 25
}

If you use PUT, the request generally provides the complete replacement representation.

If you use PATCH, you can update only the age:

{
  "age": 26
}

HTTP methods also have different safety and idempotency properties. GET is safe and idempotent. PUT and DELETE are idempotent by HTTP semantics. POST is generally neither safe nor inherently idempotent.

HTTP status codes indicate the result of an HTTP request.

They are grouped into five categories:

1xx - Informational

The request has been received and processing continues.

2xx - Success

The request was successfully received and processed.

3xx - Redirection

Additional action is needed to complete the request.

4xx - Client Errors

The request contains an issue that prevents processing.

5xx - Server Errors

The server failed to process an otherwise valid request.

In REST API development, choosing appropriate status codes makes APIs easier to understand and integrate.

A REST API request travels through multiple layers before a response is returned.

Consider a user registration request.

1. The frontend sends an HTTP POST request.
2. Express receives the request.
3. Middleware parses the JSON body.
4. The router identifies the matching endpoint.
5. Authentication middleware verifies the user if required.
6. Validation checks the incoming data.
7. The controller handles the request.
8. The service performs business logic.
9. The model interacts with MongoDB.
10. The controller returns an HTTP response.

This separation makes applications easier to maintain and test.

We will build a User Management REST API from scratch.

The API will support the following features:

User management

• Create a user.
• Retrieve all users.
• Retrieve a user by ID.
• Update a user.
• Partially update a user.
• Delete a user.

Authentication

• User registration.
• User login.
• Password hashing.
• JWT access tokens.
• Protected endpoints.

Advanced API features

• Request validation.
• Centralized error handling.
• Pagination.
• Searching.
• Filtering.
• Sorting.
• Rate limiting.
• API security.
• Automated testing.

Production readiness

• Environment configuration.
• Logging.
• Health checks.
• Graceful shutdown.
• Docker deployment.

We will use MongoDB Atlas for database hosting, but the same implementation can be adapted to a locally installed MongoDB server.