Before writing the implementation, define the API contract.

We will create the following endpoints:

Method	Endpoint	Purpose
POST	/api/v1/users	Create a user
GET	/api/v1/users	Retrieve users
GET	/api/v1/users/:id	Retrieve a specific user
PUT	/api/v1/users/:id	Replace user information
PATCH	/api/v1/users/:id	Partially update a user
DELETE	/api/v1/users/:id	Delete a user

Each endpoint will return a consistent JSON response.

We will implement the service layer first, followed by controllers and routes.

Create src/services/user.service.js.

The service layer contains business logic and database operations.

The createUser function will accept validated user information and create a MongoDB document.

We will initially implement the basic creation logic. Password hashing will be integrated when authentication is implemented.

import { User } from '../models/user.model.js';

export async function createUser(userData) {
  const user = await User.create(userData);

  return user;
}

Create src/controllers/user.controller.js.

The controller receives the HTTP request, calls the appropriate service, and sends the HTTP response.

For user creation, return status code 201 because a new resource has been created.

import * as userService from '../services/user.service.js';

export async function createUser(req, res, next) {
  try {
    const user = await userService.createUser(req.body);

    res.status(201).json({
      success: true,
      message: 'User created successfully',
      data: user
    });
  } catch (error) {
    next(error);
  }
}

Create src/routes/user.routes.js.

Use Express Router to define the user endpoints.

For now, register the create endpoint. We will add the remaining CRUD operations in the following sections.

import { Router } from 'express';
import { createUser } from '../controllers/user.controller.js';

const router = Router();

router.post('/', createUser);

export default router;

Start the server and use Postman or Bruno to send a POST request.

Endpoint:

POST http://localhost:3000/api/v1/users

Headers:

Content-Type: application/json

Request body:

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "temporary-password",
  "age": 25
}

At this stage, password hashing has not yet been implemented. Use only a disposable local database for this intermediate test, and do not expose this endpoint publicly. We will secure registration before completing authentication.

POST /api/v1/users HTTP/1.1
Host: localhost:3000
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "temporary-password",
  "age": 25
}

Now implement an endpoint that retrieves users from MongoDB.

Add the following service function to src/services/user.service.js.

Mongoose provides find() to retrieve documents matching a query.

For this initial implementation, retrieve all users. Pagination and filtering will be implemented later.

export async function getAllUsers() {
  return User.find()
    .select('-password')
    .sort({ createdAt: -1 });
}

Add a controller function that calls the getAllUsers service.

The response should contain a success flag and a data array.

Return HTTP 200 when the request succeeds.

export async function getAllUsers(req, res, next) {
  try {
    const users = await userService.getAllUsers();

    res.status(200).json({
      success: true,
      count: users.length,
      data: users
    });
  } catch (error) {
    next(error);
  }
}

Sometimes the frontend needs a specific user instead of the entire collection.

Mongoose provides findById() for retrieving a document using its MongoDB identifier.

However, malformed MongoDB ObjectIds can cause casting errors. We should validate the ID before querying the database.

export async function getUserById(userId) {
  return User.findById(userId)
    .select('-password');
}

MongoDB uses ObjectId values as document identifiers by default.

A typical ObjectId is represented as a 24-character hexadecimal string.

Before querying MongoDB, validate the identifier using Mongoose.

Mongoose provides mongoose.isValidObjectId() to check whether a value can be cast to an ObjectId.

For APIs that require a strict 24-character hexadecimal representation, use an explicit regular expression as well.

import mongoose from 'mongoose';

export function isValidUserId(userId) {
  return (
    typeof userId === 'string' &&
    /^[a-fA-F0-9]{24}$/.test(userId) &&
    mongoose.isValidObjectId(userId)
  );
}

Add the getUserById controller function.

The controller should:

1. Read the ID from req.params.
2. Validate the ID.
3. Call the service.
4. Return 404 if the user does not exist.
5. Return the user when found.

import { isValidUserId } from '../utils/user-id.js';

export async function getUserById(req, res, next) {
  try {
    const { id } = req.params;

    if (!isValidUserId(id)) {
      return res.status(400).json({
        success: false,
        message: 'Invalid user ID'
      });
    }

    const user = await userService.getUserById(id);

    if (!user) {
      return res.status(404).json({
        success: false,
        message: 'User not found'
      });
    }

    res.status(200).json({
      success: true,
      data: user
    });
  } catch (error) {
    next(error);
  }
}

We will support both PUT and PATCH operations.

For PUT, the request should provide the complete set of editable user fields.

For PATCH, only the supplied fields should be updated.

Mongoose provides findByIdAndUpdate() for updating a document by its ID.

Use the new option to return the updated document and runValidators to apply schema validators during the update.

export async function updateUser(userId, updateData) {
  return User.findByIdAndUpdate(
    userId,
    { $set: updateData },
    {
      new: true,
      runValidators: true
    }
  ).select('-password');
}

Add the PUT and PATCH routes to the user router.

Both operations can reuse the update controller, but their validation schemas should differ.

PUT represents replacement of the editable user representation.

PATCH represents partial modification.

The controller should receive the appropriate validated update payload.

router.put('/:id', updateUser);
router.patch('/:id', updateUser);

Implement user deletion using Mongoose findByIdAndDelete().

The operation should return 404 if the user does not exist.

For successful deletion, HTTP 204 No Content is appropriate when no response body is returned.

Alternatively, an API may return 200 with a confirmation message. Choose one response convention and use it consistently.

export async function deleteUser(userId) {
  return User.findByIdAndDelete(userId);
}

Add the deleteUser controller.

The controller validates the ID, calls the service, and handles missing users.

After successful deletion, send an empty 204 response.

export async function deleteUser(req, res, next) {
  try {
    const { id } = req.params;

    if (!isValidUserId(id)) {
      return res.status(400).json({
        success: false,
        message: 'Invalid user ID'
      });
    }

    const deletedUser = await userService.deleteUser(id);

    if (!deletedUser) {
      return res.status(404).json({
        success: false,
        message: 'User not found'
      });
    }

    return res.status(204).send();
  } catch (error) {
    next(error);
  }
}

Update src/routes/user.routes.js to register all CRUD endpoints.

The completed router should expose all six operations.

import { Router } from 'express';
import {
  createUser,
  getAllUsers,
  getUserById,
  updateUser,
  deleteUser
} from '../controllers/user.controller.js';

const router = Router();

router.post('/', createUser);
router.get('/', getAllUsers);
router.get('/:id', getUserById);
router.put('/:id', updateUser);
router.patch('/:id', updateUser);
router.delete('/:id', deleteUser);

export default router;