Standardized Paging Architectures

In this lesson, you will learn how to build reusable middleware that standardizes how your API handles large datasets through both offset-based and cursor-based pagination.

Why Standardize Pagination?

When clients fetch thousands of records, returning everything at once crashes your server and overwhelms the network. While you could manually add limit and offset logic to every route, that leads to code duplication. By creating middleware, you ensure that every API endpoint follows the same contract, making your front-end integration predictable and your backend maintainable.

Implementing the Middleware

A standardized pagination middleware intercepts the request, validates the incoming parameters, and injects a pagination object into the req context—leveraging the Request Context Injection pattern you learned previously.

const paginationMiddleware = (req, res, next) => {
  const { limit, offset, cursor } = req.query;

  // Standardizing defaults
  req.pagination = {
    limit: parseInt(limit) || 20,
    offset: parseInt(offset) || 0,
    cursor: cursor || null,
    isCursorBased: !!cursor
  };

  next();
};

Offset vs. Cursor

• Offset-based (limit/offset): Great for jumping to specific pages (e.g., "Page 3"). However, it is slow on deep datasets because the database must scan all preceding records.
• Cursor-based (cursor): Uses a pointer to a specific record (often a timestamp or unique ID). This is significantly faster for large, real-time datasets because the query starts exactly where the previous batch left off.

By handling this in middleware, your controllers don't need to know how the request was parsed. They simply query the database using req.pagination. If you later decide to change the default limit from 20 to 50 across your entire application, you only have to update this single file.

Consistency Through Middleware

Using this approach, you can also append metadata (like totalCount or nextCursor) to the response headers automatically, ensuring your Modular Error Handling and API Usage Billing Hooks have a consistent structure to read from.

Key Takeaway: Standardizing pagination via middleware decouples request parsing from business logic, ensuring your API remains predictable, performant, and easy to scale.