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

  1. Define a Route:

Add a route for the API endpoint in routes/api.php:


   Route::get('/posts', [PostController::class, 'index']);
  1. 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

  1. 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(),
           ],
       ]);
   }
  1. 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

  1. 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.
  1. 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,
           ],
       ]);
   }
  1. 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

  1. 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(),
           ],
       ]);
   }
  1. 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

  1. Test API Responses:

Use tools like Postman or Insomnia to verify:

  • Pagination metadata.
  • Links for next/previous pages.
  • Cursor behavior.
  1. 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.