Building a Paginated History API with NestJS and TypeORM
Introduction
Handling large datasets efficiently is a common challenge in API development. When dealing with historical records, exposing all data at once is rarely an option due to performance implications and poor user experience. This is where pagination becomes essential. In the Acelerador 2.0 project, we recently implemented a robust, paginated API endpoint to retrieve historical 'editions,' complete with team counts and ordered by their start dates.
Implementing a Paginated History Endpoint
The core of this feature involves creating a new GET /edition/history endpoint. This endpoint is designed to return a paginated list of all past editions, ensuring that the most recent historical entries appear first. We achieved this by ordering the results by startDate in descending order.
Using NestJS, the process involves defining a controller to handle the incoming HTTP request and a service layer to encapsulate the business logic and interact with the database. The Repository Pattern, powered by TypeORM, provides a clean abstraction for database operations.
Key considerations for this endpoint included:
- Pagination: Accepting
pageandlimitparameters to control the dataset size. - Ordering: Ensuring results are consistently ordered by a relevant field (
startDatedescending). - Data Enrichment: Including derived data like the number of teams (
teamCount) per edition directly within the response.
Ensuring Database Compatibility: The timestamp Fix
During development, it's crucial to align data types with the underlying database system. A common pitfall, especially when working with PostgreSQL, is the handling of date and time fields. We identified and corrected an inconsistency where datetime was being used in entity definitions instead of timestamp.
While some databases might be forgiving, timestamp is generally the more robust and compatible choice for storing precise date and time values across different relational database systems, including PostgreSQL. This small but significant correction ensures data integrity and prevents potential issues with date calculations and comparisons.
API Documentation with Swagger
Clear API documentation is paramount for any successful project, enabling both frontend developers and other services to easily understand and consume the API. We integrated Swagger (OpenAPI) into the NestJS application to automatically generate interactive API documentation.
By leveraging Swagger decorators, our new /edition/history endpoint is fully documented, detailing its purpose, expected query parameters (page, limit), and the structure of its successful response. This ensures that anyone interacting with the API has an up-to-date and accurate reference.
A Practical Example
Here’s a simplified look at how the controller and service might be structured in NestJS using TypeORM to achieve the paginated history endpoint:
// editions.controller.ts
import { Controller, Get, Query, DefaultValuePipe, ParseIntPipe } from '@nestjs/common';
import { ApiTags, ApiQuery, ApiResponse } from '@nestjs/swagger';
import { EditionsService } from './editions.service';
@ApiTags('Editions')
@Controller('edition')
export class EditionsController {
constructor(private readonly editionsService: EditionsService) {}
@Get('history')
@ApiQuery({ name: 'page', required: false, type: Number, description: 'Page number', example: 1 })
@ApiQuery({ name: 'limit', required: false, type: Number, description: 'Items per page', example: 10 })
@ApiResponse({ status: 200, description: 'Paginated list of historical editions.' })
async getEditionHistory(
@Query('page', new DefaultValuePipe(1), ParseIntPipe) page: number,
@Query('limit', new DefaultValuePipe(10), ParseIntPipe) limit: number,
) {
return this.editionsService.findHistoricalEditions(page, limit);
}
}
// editions.service.ts
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { EditionEntity } from './edition.entity'; // Assume EditionEntity is defined
@Injectable()
export class EditionsService {
constructor(
@InjectRepository(EditionEntity)
private readonly editionRepository: Repository<EditionEntity>,
) {}
async findHistoricalEditions(page: number, limit: number) {
const skip = (page - 1) * limit;
const [editions, total] = await this.editionRepository.findAndCount({
order: { startDate: 'DESC' },
take: limit,
skip: skip,
// In a real scenario, teamCount might be a calculated field
// via a JOIN or a subquery, or a separate repository call.
// For this example, we'll simulate adding it.
});
const editionsWithTeamCount = editions.map(edition => ({
...edition,
teamCount: Math.floor(Math.random() * 20) + 1 // Placeholder for actual logic
}));
return {
data: editionsWithTeamCount,
total,
page,
limit,
totalPages: Math.ceil(total / limit),
};
}
}
The controller handles request parsing, while the service leverages TypeORM's findAndCount method to efficiently retrieve both the paginated data and the total count, crucial for calculating total pages.
Conclusion
Developing scalable and maintainable APIs requires careful consideration of data exposure and documentation. By implementing paginated endpoints, ensuring database compatibility, and providing clear API documentation with tools like Swagger, we build APIs that are both performant and easy to use. Always prioritize robust data handling and clear communication in your API design.
Generated with Gitvlg.com