Laravel's default pagination system is robust for standard web applications, but API responses often require custom structures to meet front-end requirements or adhere to RESTful standards. This tutorial demonstrates how to build a tailored pagination system for API responses, including metadata, links, and cursor-based pagination.
Scenario: Custom API Pagination
Imagine you’re building an API where:
- The front-end requires a specific JSON structure for pagination data.
- You need metadata like the total number of items, current page, and links for next/previous pages.
- Cursor-based pagination is preferred over traditional offset-based pagination for large datasets.
We’ll implement a custom solution to meet these needs.
Step 1: Create a Basic API Endpoint
- Define a Route:
Add a route for the API endpoint in routes/api.php:
Route::get('/posts', [PostController::class, 'index']);
- Set Up the Controller:
Create the controller:
php artisan make:controller PostController
Add a basic index method:
namespace App\Http\Controllers;
use App\Models\Post;
class PostController extends Controller
{
public function index()
{
$posts = Post::paginate(10); // Default pagination
return response()->json($posts);
}
}
Step 2: Customize the API Response Structure
- Transform the Pagination Response:
Modify the response structure to include metadata and links:
use Illuminate\Http\Request;
public function index(Request $request)
{
$posts = Post::paginate(10);
return response()->json([
'data' => $posts->items(), // The paginated items
'meta' => [
'current_page' => $posts->currentPage(),
'per_page' => $posts->perPage(),
'total' => $posts->total(),
'last_page' => $posts->lastPage(),
],
'links' => [
'next' => $posts->nextPageUrl(),
'previous' => $posts->previousPageUrl(),
],
]);
}
- Example JSON Response:
{
"data": [
{ "id": 1, "title": "Post 1" },
{ "id": 2, "title": "Post 2" }
],
"meta": {
"current_page": 1,
"per_page": 10,
"total": 50,
"last_page": 5
},
"links": {
"next": "http://example.com/api/posts?page=2",
"previous": null
}
}
Step 3: Add Cursor-Based Pagination
- Why Use Cursor-Based Pagination?
- Cursor-based pagination is faster for large datasets since it avoids calculating offsets.
- Instead of page numbers, it uses a cursor (e.g., a timestamp or ID) to fetch the next set of results.
- Implement Cursor-Based Logic:
Modify the query to use a cursor:
public function index(Request $request)
{
$limit = $request->get('limit', 10);
$cursor = $request->get('cursor');
$query = Post::query();
if ($cursor) {
$query->where('id', '>', $cursor); // Fetch items after the cursor
}
$posts = $query->orderBy('id')->take($limit + 1)->get();
$nextCursor = $posts->count() > $limit ? $posts->last()->id : null;
return response()->json([
'data' => $posts->take($limit), // Return only the requested number of items
'meta' => [
'limit' => $limit,
'next_cursor' => $nextCursor,
],
]);
}
- Example JSON Response with Cursor:
{
"data": [
{ "id": 11, "title": "Post 11" },
{ "id": 12, "title": "Post 12" }
],
"meta": {
"limit": 10,
"next_cursor": 20
}
}
Step 4: Add Flexible Query Parameters
- Allow Sorting:
Add query parameters for sorting:
public function index(Request $request)
{
$sortBy = $request->get('sort_by', 'id');
$sortOrder = $request->get('sort_order', 'asc');
$posts = Post::orderBy($sortBy, $sortOrder)->paginate(10);
return response()->json([
'data' => $posts->items(),
'meta' => [
'current_page' => $posts->currentPage(),
'per_page' => $posts->perPage(),
'total' => $posts->total(),
'last_page' => $posts->lastPage(),
],
'links' => [
'next' => $posts->nextPageUrl(),
'previous' => $posts->previousPageUrl(),
],
]);
}
- Allow Filtering:
Add query parameters for filtering:
public function index(Request $request)
{
$title = $request->get('title');
$query = Post::query();
if ($title) {
$query->where('title', 'like', '%' . $title . '%');
}
$posts = $query->paginate(10);
return response()->json([
'data' => $posts->items(),
'meta' => [
'current_page' => $posts->currentPage(),
'per_page' => $posts->perPage(),
'total' => $posts->total(),
'last_page' => $posts->lastPage(),
],
'links' => [
'next' => $posts->nextPageUrl(),
'previous' => $posts->previousPageUrl(),
],
]);
}
Step 5: Test and Debug Your Pagination System
- Test API Responses:
Use tools like Postman or Insomnia to verify:
- Pagination metadata.
- Links for next/previous pages.
- Cursor behavior.
- Write Unit Tests:
Test paginated responses:
public function testApiPagination()
{
$response = $this->get('/api/posts?page=1');
$response->assertStatus(200)
->assertJsonStructure([
'data' => [['id', 'title']],
'meta' => ['current_page', 'per_page', 'total', 'last_page'],
'links' => ['next', 'previous'],
]);
}
Test cursor-based pagination:
public function testCursorPagination()
{
$response = $this->get('/api/posts?cursor=10');
$response->assertStatus(200)
->assertJsonStructure([
'data' => [['id', 'title']],
'meta' => ['limit', 'next_cursor'],
]);
}
Key Takeaways
- Customize API pagination to fit front-end requirements with tailored JSON structures.
- Use cursor-based pagination for performance improvements in large datasets.
- Add flexibility with sorting and filtering parameters.
- Test your pagination system thoroughly for edge cases.
Conclusion
Building a custom pagination system for API responses in Laravel ensures that your application meets the specific needs of front-end clients and scales effectively. By combining metadata, flexible queries, and cursor-based pagination, you can deliver optimized and user-friendly APIs.