DEV Community: Gul Zaib

Best Practices for Returning API Responses in Express.js Controllers

Gul Zaib — Sat, 15 Feb 2025 18:56:16 +0000

When building APIs with Express.js , it's crucial to follow best practices for structuring and returning API responses. A well-designed API not only improves developer experience but also ensures consistency, scalability, and maintainability of your codebase. In this article, we’ll explore some key principles and patterns for returning API responses in Express.js controllers.

1. Use Consistent Response Structures

Consistency is key when designing APIs. Every response should follow a predictable structure so that clients know what to expect. A common pattern is to include three main components in every response:

Status : Indicates whether the request was successful or not.
Message : Provides a human-readable description of the result.
Data : Contains the payload or result of the operation (if applicable).

Here’s an example of a consistent response structure:

{
  "status": "success",
  "message": "User retrieved successfully",
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "john.doe@example.com"
  }
}

For error responses, you can use a similar structure but with an error field instead of data:

{
  "status": "error",
  "message": "Invalid credentials",
  "error": {
    "code": 401,
    "details": "The provided email or password is incorrect."
  }
}

2. Leverage Middleware for Error Handling

In Express.js, middleware functions are a powerful way to handle errors consistently across your application. Instead of handling errors inline within each route, you can create a centralized error-handling middleware.

Here’s an example of an error-handling middleware:

// Error-handling middleware
function errorHandler(err, req, res, next) {
  console.error(err.stack);

  const statusCode = err.statusCode || 500;
  const message = err.message || 'Internal Server Error';

  res.status(statusCode).json({
    status: 'error',
    message: message,
    error: {
      code: statusCode,
      details: err.details || 'Something went wrong on the server.'
    }
  });
}

// Use the middleware in your app
app.use(errorHandler);

Now, whenever an error occurs in your routes, you can pass it to the next() function, and the middleware will handle it:

app.get('/user/:id', async (req, res, next) => {
  try {
    const user = await User.findById(req.params.id);
    if (!user) {
      throw { statusCode: 404, message: 'User not found' };
    }
    res.json({
      status: 'success',
      message: 'User retrieved successfully',
      data: user
    });
  } catch (err) {
    next(err); // Pass the error to the error-handling middleware
  }
});

3. Use HTTP Status Codes Appropriately

HTTP status codes provide a standardized way to indicate the result of an API request. Always use the appropriate status code to reflect the outcome of the operation. Here are some common status codes and their use cases:

200 OK : The request was successful.
201 Created : A new resource was successfully created.
400 Bad Request : The request was invalid or malformed.
401 Unauthorized : Authentication is required or has failed.
403 Forbidden : The client does not have permission to access the resource.
404 Not Found : The requested resource could not be found.
500 Internal Server Error : An unexpected error occurred on the server. For example, when creating a new user, you might return a 201 Created status code:

app.post('/users', async (req, res, next) => {
  try {
    const newUser = await User.create(req.body);
    res.status(201).json({
      status: 'success',
      message: 'User created successfully',
      data: newUser
    });
  } catch (err) {
    next(err);
  }
});

4. Validate Input Data

Validating input data is essential to ensure that your API receives the correct information and prevents malicious or malformed requests. You can use libraries like Joi or express-validator to validate request data.

Here’s an example using express-validator :

const { body, validationResult } = require('express-validator');

app.post(
  '/users',
  [
    body('name').notEmpty().withMessage('Name is required'),
    body('email').isEmail().withMessage('Invalid email address'),
    body('password').isLength({ min: 6 }).withMessage('Password must be at least 6 characters')
  ],
  (req, res, next) => {
    const errors = validationResult(req);
    if (!errors.isEmpty()) {
      return res.status(400).json({
        status: 'error',
        message: 'Validation failed',
        error: {
          code: 400,
          details: errors.array()
        }
      });
    }

    // Proceed with creating the user
    next();
  }
);

5. Paginate Large Datasets

When dealing with large datasets, it’s important to paginate your responses to improve performance and reduce the load on both the server and the client. Include pagination metadata in your response to help clients navigate through the data.

Here’s an example of a paginated response:

{
  "status": "success",
  "message": "Users retrieved successfully",
  "data": [
    { "id": 1, "name": "John Doe" },
    { "id": 2, "name": "Jane Smith" }
  ],
  "pagination": {
    "total": 100,
    "page": 1,
    "limit": 10,
    "pages": 10
  }
}

You can implement pagination in Express.js like this:

app.get('/users', async (req, res, next) => {
  try {
    const page = parseInt(req.query.page) || 1;
    const limit = parseInt(req.query.limit) || 10;

    const users = await User.find()
      .skip((page - 1) * limit)
      .limit(limit);

    const total = await User.countDocuments();

    res.json({
      status: 'success',
      message: 'Users retrieved successfully',
      data: users,
      pagination: {
        total,
        page,
        limit,
        pages: Math.ceil(total / limit)
      }
    });
  } catch (err) {
    next(err);
  }
});

6. Secure Your API Responses

Always sanitize and filter sensitive data before sending it in API responses. For example, avoid exposing sensitive fields like passwords or tokens in your responses.

Here’s an example of how to exclude sensitive fields:

app.get('/user/:id', async (req, res, next) => {
  try {
    const user = await User.findById(req.params.id).select('-password');
    if (!user) {
      throw { statusCode: 404, message: 'User not found' };
    }
    res.json({
      status: 'success',
      message: 'User retrieved successfully',
      data: user
    });
  } catch (err) {
    next(err);
  }
});

Conclusion

By following these best practices, you can build robust, scalable, and maintainable APIs with Express.js. Consistent response structures, proper error handling, appropriate HTTP status codes, input validation, pagination, and security measures are all critical components of a well-designed API.

Remember, the goal is to make your API intuitive and easy to use for developers, while ensuring that it remains secure and performant. Happy coding!

Optimizing PHP Applications: Why Separate Read and Write Models Matter

Gul Zaib — Sat, 15 Feb 2025 18:42:26 +0000

Models are a great tool to communicate with a data storage. We can define how the data looks like, and that makes sure that it’s compatible with the data storage, typically a database. Once we have a model that validates our input and helps us write that data we could be tempted to use it also for retrieving data. Except for some basic CRUD applications, that is not usually such a good idea. Let’s see why.

Set up a model to work with

Let’s use a simple User model and the interface of a repository, we don’t really need the details here. But let’s assume we have some assertion library that we use to validate that every model created is valid.

class User
{
    public function __construct(
        public string $email,
        public string $name,
        public string $password,
    ) {
        Assert::email($email);
        Assert::notEmpty($name);
        Assert::password($password, strength: 3);
    }
}
interface UserRepository
{
    public function save(User $user): void;
}

So main use case, we get data for a new user, it validates that the name is not empty, the email is a valid email and that the password complies with whatever we defined as strength level 3. Then we send it to the repository and save it. Job done.

$user = new User(
    $request->get('email'),
    $request->get('name'),
    $request->get('password'),
);
$repository->save($user);

Problem: Model properties that should not be read

So now we want to read a user by email from the database to return a json representation of it for a client to present some user profile. What happens if we add a read method to our repository reusing the same model?

interface UserRepository
{
    public function save(User $user): void;
    public function get(string $email): User;
}
// Inside some controller class
return new Response(
    json_encode(
        $repository->get($request->get('email'))
    ),
);

So what are we getting here?

{
  "email": "peter@dailybugle.com",
  "name": "Peter Parker",
  "password": "$2y$10$OEaTphGkW0HQv4QNxtptQOE.BSQDnpwrB.\/VGqIgjMEhvIr22jnFK"
}

The first thing that should cross our minds when we watch this is that passwords, even encrypted, should never, ever be sent in any kind of communication from the server. So this is an important security concern.

Even if this is probably the worst possible case of an information leak caused by using a write model as a read model, it’s not the only one. Another common issue is just sending irrelevant information to the client. For example, we could have an active boolean we can use for enabling or disabling users that would be useless for the client, because if the user is not active the request will respond with a 404 Not Found. Irrelevant data means that we are sending bytes that will never be consumed, hurting performance. It may be little, but everything adds and this has an easy solution.

So what do we do? Provide a return with a restricted list of data? This could solve these problems.

class User
{
    // ...

    public function read(): array
    {
        return [
            'email' => $this->email,
            'name' => $this->name,
        ];
    }
}

But there are more issues to solve, let’s see.

Problem: Unnecessary validations

Talking about performance, we have validations in the model constructor, but are those needed when we fetch data that is already in the database? They must have been valid the moment they were stored, so it can be argued that running those validations again is a waste.

But not only a waste, it can be a real problem. Validations might evolve and that can impact the ability to fetch results if we use a write model which makes use of validations. Suppose an application that validates that emails for users have a valid email format, but at some point another rule is added to blacklist some domains in email addresses. The validation is updated, but the existing users can’t really be updated, because they still expect communications via that email address.

Now we get a request for a list of 100 users in which one of them has a blacklisted domain, what happens? The whole request is considered an error. And what do we send the user? A 400 Bad Request response like if some user input was wrong? This is not the client’s fault but the server’s. In this case it should be some kind of 500 error.

To avoid this, I’ve seen some complex solutions involving Reflection and an instance without constructor. If we really had to use the write model in cases we don’t want to validate I would move the assertions to a static constructor though, like this.

class User
{
    public function __construct(
        public string $email,
        public string $name,
        public string $password,
    ) {}

    public static function create(string $email, string $name, string $password): self
    {
        Assert::email($email);
        Assert::notEmpty($name);
        Assert::password($password, strength: 3);

        return new self($email, $name, $password);
    }
}

This way, when creating a new model that requires validation I can do User::new(), and use the constructor when fetching data from the database. Solves some issues, but there are more.

Problem: Adding extra data to the model

Another common situation is the client requiring some more data for the view. In our example, the view might need to show the number of comments that a user has created in the system. That’s not part of the model, but it looks wasteful not to add that in the same HTTP response and keep the client waiting for a second one just because the data does not match the write model.

Even if we try to add the data in the same request, sticking to this write model means that we can’t use a single database request to get the whole set of data, though in many cases that could be solved with a simple SQL join. Instead we get the write model and then do another database request to fetch the missing data, and compose it before sending it to the client.

return new Response(
    json_encode(
        array_merge(
            $repository->get($request->get('email')),
            ['comments' => $commentRepository->count($request->get('email'))]
        )

    ),
);

It works, but it means an extra database query with it’s impact in the performance. And it also hurts re-usability, as you can’t just call the repository somewhere else, you also need to copy and paste the comments part.

Problem: Are inserts and updates really the same?

For a last problem, this is not really a write vs read model, but when we are updating a model, can we really use the same class that we use when creating it?

So if we create a new user with this model, we expect name, email and password. For creating a user that’s ok, but in our example our security expert requires that passwords are updated in a specific way, which involves the user requesting a password change, an email being sent to the user with a limited time token and then validating that token to accept the new password.

The password should never be updated in any other way, so what do we do if we use the same model we already have for updating the user? We will have two different places in the code where we update the user, one for password, another for anything else.

interface UserRepository
{
    public function save(User $user): void;
    public function update(User $user): void;
}
// Updating name
$user = new User(
    $request->get('email'),
    $request->get('name'),
    'WHAT DO WE DO WITH PASSWORD HERE?',
);

$repository->update($user);
// Updating password
$user = new User(
    $request->get('email'),
    'WHAT DO WE DO WITH NAME HERE?',
    $request->get('password'),
);

$repository->update($user);

Now we have to deal with data in the model that must not be processed, which will make our repository implementation unnecessarily more complex. It will also force the model creation to provide data that will not be available and will not be used, making code much harder to understand. And finally, we introduce a fragile implementation that, if used incorrectly, can cause the update of something that should not be updated, just because it is in the model. If we process the user name change in a way that triggers a password update, that’s a serious problem.

Solution: Individual model for each case

How can we solve all the problems when reading a user? A dedicated model will do.

final readonly class UserRead
{
    public function __construct(
        public string $email,
        public string $name,
        public int $commentCount,
    ) {}
}

We can have another repository to fetch it.

interface UserReadRepository
{
    public function get(string $email): UserRead;
}

This implementation, assuming a relational SQL database, would not select the password form the table which is not in the read model, solving problem number 1. This read model does not include validations solving problem number 2. And this model has a place for the comments count that can be implemented in the new repository by using a join in a single query, solving problem number 3.

Even more, if we have more representations of a user, we should have a different read model to cover each one. We could have a UserWithLastCommentsRead for example.

And for the update problems? You probably guessed. Individual models for each update.

final readonly class UserDataUpdate
{
    public function __construct(
        public string $email,
        public string $name,
    ) {
        Assert::notEmpty($name);
    }
}
final readonly class UserPasswordUpdate
{
    public function __construct(
        public string $email,
        public string $password,
    ) {
        Assert::password($password, strength: 3);
    }
}
interface UserRepository
{
    public function save(User $user): void;
    public function updateData(UserDataUpdate $userDataUpdate): void;
    public function updatePassword(UserPasswordUpdate $userPasswordUpdate): void;
}

Now there are no mistakes or unnecessary data. Each update is isolated and it is much more protected from bugs.

Note that in the update models I didn’t add the email validation. That is intentional because it is going to be used to find the user, and if we have an evolved validation, as commented before, we would not be able to find older users with emails that are not valid anymore, but still in the database anyways.

Last words

This is really not that different as we model objects in the real world. We never consider everything about a real life object in a particular context. For example a car.

If a car is modeled by a driver, we can expect the positioning of the seat and the rear mirrors to be really important, while at the same time it is irrelevant for a mechanic doing some maintenance. The mechanic will probably be more concerned about metrics on the engine that are not important to the driver. And a kid at the school learning about transport methods will probably just care about it being a land transport with 4 wheels.

If we use different models for the same real life objects we can definitely do the same for our code models.

Mastering Array Sorting in PHP: usort & uasort 🚀🚀

Gul Zaib — Fri, 06 Oct 2023 12:19:00 +0000

Array sorting is a fundamental operation in PHP, and it's crucial for organizing data efficiently. While PHP provides built-in sorting functions, such as sort and asort, there are times when you need more advanced sorting techniques. In this blog post, we'll explore advanced array sorting using usort, uasort, and custom comparison functions.

Understanding the Basics

Before diving into advanced sorting, let's briefly review the basic sorting functions in PHP:

sort: Sorts an array in ascending order by values, reindexing the array.
asort: Sorts an associative array in ascending order by values, maintaining key-value associations.
rsort and arsort: Sorts arrays in descending order.
ksort and krsort: Sorts arrays by keys.
natsort: Sorts an array using natural order algorithm. Now, let's explore advanced sorting.

`usort`: User-Defined Sort

usort stands for "user-defined sort." It allows you to sort an array using a custom comparison function. This function defines the sorting logic based on your specific criteria. Here's an example:

function customSort($a, $b) {
    // Sort by 'name' field
    return strcmp($a['name'], $b['name']);
}

$data = [
    ['name' => 'John'],
    ['name' => 'Alice'],
    ['name' => 'Bob']
];

usort($data, 'customSort');

In this example, we define the customSort function, which compares elements based on their 'name' field. The usort function takes care of sorting the array according to this custom logic.

`uasort`: User-Defined Associative Sort

uasort is similar to usort, but it's designed for associative arrays. It allows you to sort an associative array using a custom comparison function while maintaining key-value associations:

function customSort($a, $b) {
    // Sort values in ascending order
    return strcmp($a, $b);
}

$data = [
    'b' => 'Alice',
    'a' => 'John',
    'c' => 'Bob'
];

uasort($data, 'customSort');

In this example, we use uasort to sort values in ascending order while keeping the keys intact.

Custom Comparison Functions

Custom comparison functions give you full control over how you want to sort your arrays. You can compare elements based on specific fields, data types, or complex conditions. Here's an example sorting an array of students by their scores:

function customSort($a, $b) {
    if ($a['score'] == $b['score']) {
        return 0;
    }
    // Sort by 'score' in ascending order
    return ($a['score'] < $b['score']) ? -1 : 1;
}

$data = [
    ['name' => 'John', 'score' => 85],
    ['name' => 'Alice', 'score' => 92],
    ['name' => 'Bob', 'score' => 78]
];

usort($data, 'customSort');

Here, we define the customSort function to sort students based on their scores in ascending order.

Conclusion

Advanced array sorting is a powerful tool in PHP, allowing you to tailor sorting to your specific needs. Whether you're sorting complex data structures, associative arrays, or using custom criteria, usort, uasort, and custom comparison functions provide the flexibility you need to master array sorting in PHP.

Mastering PHP Foreach Loops: The Power of '&' for References ⚡🚀

Gul Zaib — Thu, 05 Oct 2023 11:55:34 +0000

Introduction

PHP, a versatile scripting language, offers a range of features to make developers' lives easier. Among these, the foreach loop stands out as a convenient tool for iterating over arrays and objects. However, there's a hidden gem within PHP's foreach loops – the use of the & symbol. In this comprehensive guide, we'll delve into the world of PHP foreach loops and explore how leveraging the & symbol can take your coding skills to the next level.

Understanding PHP Foreach Loops

Before we dive into the specifics of the & symbol, let's revisit the basics of PHP foreach loops. These loops are designed for iterating over arrays and objects, providing a clean and concise way to access and manipulate their elements.

$fruits = ['apple', 'banana', 'cherry'];

foreach ($fruits as $fruit) {
    echo $fruit . ' ';
}
// Output: apple banana cherry

The Power of '&' – Creating References

The & symbol in PHP foreach loops allows us to create references to array elements or object properties rather than working with copies. This distinction can have a profound impact on how you manipulate data within the loop.

$fruits = ['apple', 'banana', 'cherry'];

foreach ($fruits as &$fruit) {
    $fruit = strtoupper($fruit);
}

// $fruits now contains ['APPLE', 'BANANA', 'CHERRY']

Here, we've transformed the original array's elements to uppercase using the reference created with &.

Common Use Cases for '&' in Foreach Loops

While not every loop requires the use of &, there are situations where it can be incredibly useful:

Modifying Array Elements by Reference

$numbers = [1, 2, 3, 4];
foreach ($numbers as &$number) {
    $number *= 2;
}
// $numbers becomes [2, 4, 6, 8]

Creating Dynamic References

$variables = ['var1', 'var2', 'var3'];
foreach ($variables as $varName) {
    $$varName = 'initialized';
}
// $var1, $var2, and $var3 are now initialized variables

Efficiently Handling Large Datasets

// Process large dataset efficiently using references
$largeData = fetchData();
foreach ($largeData as &$dataItem) {
    processData($dataItem);
}

Pitfalls and Best Practices

While using & in foreach loops can be powerful, it comes with potential pitfalls. Here are some best practices to keep in mind:

Unset References

$fruits = ['apple', 'banana', 'cherry'];
foreach ($fruits as &$fruit) {
    // Some logic here
}
unset($fruit); // Important to unset the reference

Avoid Nesting References

$matrix = [[1, 2], [3, 4]];
foreach ($matrix as &$row) {
    foreach ($row as &$value) {
        // Avoid nesting references – can lead to unexpected behavior
    }
}

Alternatives to '&' in Foreach Loops

In some cases, you can achieve similar results without using references:

Using array_map

$numbers = [1, 2, 3, 4];
$numbers = array_map(function ($number) {
    return $number * 2;
}, $numbers);
// $numbers becomes [2, 4, 6, 8]

Conclusion

Mastering PHP foreach loops and understanding the power of & for references can significantly improve your coding efficiency. While this feature should be used judiciously to avoid unintended consequences, it offers a valuable tool for working with arrays and objects. By following best practices and considering alternatives, you can confidently navigate the world of PHP loops and elevate your programming skills.

Concurrency Management: How Web Servers Keep the Show Running Smoothly ⚡🚀

Gul Zaib — Wed, 04 Oct 2023 20:22:05 +0000

In the realm of web development, the ability to efficiently handle multiple client requests concurrently is a fundamental aspect of ensuring a responsive and scalable web application. PHP, a popular server-side scripting language, plays a crucial role in this process. In this blog post, we will delve into how PHP and the PHP server achieve this by isolating and managing variables and data separately for each request.

Introduction

Concurrency, in the context of web development, refers to the ability of a web server to process multiple incoming client requests simultaneously. It's vital for ensuring that a web application can serve many users without slowing down or crashing.

Web Server Setup

To understand how PHP manages concurrent requests, let's start with the setup. Most web servers (e.g., Apache or Nginx) use a multi-process or multi-threaded model to handle incoming HTTP requests. This means that the web server can spawn multiple PHP processes or threads to execute scripts in parallel.

Concurrency Models

Multi-Process Model

In the multi-process model, the web server creates a separate process for each incoming request. Each process runs independently, allowing multiple requests to be processed simultaneously. This model is advantageous for stability because if one process crashes, it doesn't affect others.

Multi-Threaded Model

Some web servers use multiple threads instead of processes. Each thread can handle one request at a time, but multiple threads can run concurrently. This model is more memory-efficient but can be less robust since a problem in one thread can affect the entire server.

Example: Imagine you're running a popular e-commerce website, and it's Black Friday. This means a massive influx of users trying to snag the best deals simultaneously. To handle this surge in traffic, your web server uses multiple PHP processes, each responsible for a client's request.

Isolation of Variables

One key aspect of handling concurrent requests is the isolation of variables and data. When a client makes an HTTP request, a new PHP process or thread is spawned to handle that specific request. Variables declared within a PHP script are local to that process or thread, ensuring that they do not interfere with variables in other concurrent requests.

Data Storage and Retrieval

Data retrieval during the execution of a PHP script is also isolated for each request. For example, if a script connects to a database, each request has its own database connection or resource handle. This ensures that data retrieved during one request does not conflict with data retrieval for other requests.

Response Generation and Sending

After processing a request, the PHP script generates an HTTP response, typically in the form of HTML or other content. This response is sent back to the requesting client. Importantly, the response generated for one request does not mix with the response for another request because each response is sent separately.

Concurrency Management

Web servers are responsible for managing concurrent requests efficiently. They queue incoming requests and allocate resources (processes or threads) as needed to ensure that multiple requests are processed in parallel without conflicts.

Benefits of Concurrency Handling

Efficient concurrent request handling offers several benefits, including improved application responsiveness, scalability, and the ability to serve many users simultaneously. It's essential for modern web applications.

Real-World Scenarios

Explore real-world scenarios where PHP's concurrent request handling shines. This could include e-commerce platforms handling simultaneous user orders, social media sites serving multiple users' feeds, or content delivery networks (CDNs) distributing content efficiently.

Conclusion

In conclusion, PHP's ability to handle multiple client requests concurrently by isolating and managing variables and data separately for each request is a crucial aspect of web development. It ensures that web applications can provide a smooth and responsive user experience even under heavy load.

DEV Community: Gul Zaib

Best Practices for Returning API Responses in Express.js Controllers

1. Use Consistent Response Structures

2. Leverage Middleware for Error Handling

3. Use HTTP Status Codes Appropriately

4. Validate Input Data

5. Paginate Large Datasets

6. Secure Your API Responses

Conclusion

Optimizing PHP Applications: Why Separate Read and Write Models Matter

Set up a model to work with

Problem: Model properties that should not be read

Problem: Unnecessary validations

Problem: Adding extra data to the model

Problem: Are inserts and updates really the same?

Solution: Individual model for each case

Last words

Mastering Array Sorting in PHP: usort & uasort 🚀🚀

Understanding the Basics

usort: User-Defined Sort

uasort: User-Defined Associative Sort

Custom Comparison Functions

Conclusion

Mastering PHP Foreach Loops: The Power of '&' for References ⚡🚀

Introduction

Understanding PHP Foreach Loops

The Power of '&' – Creating References

Common Use Cases for '&' in Foreach Loops

Modifying Array Elements by Reference

Creating Dynamic References

Efficiently Handling Large Datasets

Pitfalls and Best Practices

Unset References

Avoid Nesting References

Alternatives to '&' in Foreach Loops

Using array_map

Conclusion

Concurrency Management: How Web Servers Keep the Show Running Smoothly ⚡🚀

Introduction

Web Server Setup

Concurrency Models

Multi-Process Model

Multi-Threaded Model

Isolation of Variables

Data Storage and Retrieval

Response Generation and Sending

Concurrency Management

Benefits of Concurrency Handling

Real-World Scenarios

Conclusion

`usort`: User-Defined Sort

`uasort`: User-Defined Associative Sort