How to Implement Pagination in API in Laravel Easily

In Laravel, you can implement pagination in an API by using the paginate() method on your Eloquent query. This method automatically splits results into pages and returns JSON with pagination info, which you can return directly from your API controller.

Syntax

The paginate() method is called on an Eloquent query builder instance. It accepts the number of items per page as an argument and returns a LengthAwarePaginator instance with data and pagination details.

• Model::paginate(10) - fetches 10 items per page.
• The paginator includes metadata like current_page, last_page, per_page, and total.
• Use ->toJson() or return directly in API response for JSON output.

php

use App\Models\Post;

$posts = Post::paginate(10);

return response()->json($posts);

Example

This example shows a simple API controller method that returns paginated posts with 5 items per page. The JSON response includes the posts data and pagination info like total pages and current page.

php

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Models\Post;
use Illuminate\Http\Request;

class PostController extends Controller
{
    public function index(Request $request)
    {
        // Paginate posts, 5 per page
        $posts = Post::paginate(5);

        // Return paginated data as JSON
        return response()->json($posts);
    }
}

Output

{
  "current_page": 1,
  "data": [
    {"id":1,"title":"Post 1","content":"..."},
    {"id":2,"title":"Post 2","content":"..."},
    {"id":3,"title":"Post 3","content":"..."},
    {"id":4,"title":"Post 4","content":"..."},
    {"id":5,"title":"Post 5","content":"..."}
  ],
  "first_page_url": "http://yourapp.test/api/posts?page=1",
  "from": 1,
  "last_page": 10,
  "last_page_url": "http://yourapp.test/api/posts?page=10",
  "links": [],
  "next_page_url": "http://yourapp.test/api/posts?page=2",
  "path": "http://yourapp.test/api/posts",
  "per_page": 5,
  "prev_page_url": null,
  "to": 5,
  "total": 50
}

Common Pitfalls

Common mistakes when implementing pagination in Laravel APIs include:

• Not using paginate() and instead using get(), which returns all results without pagination.
• Forgetting to return the paginator object as JSON, which can cause errors or unexpected output.
• Not handling the page query parameter, which Laravel does automatically but you must ensure your frontend sends it.
• Using simplePaginate() when you need total count info, as it returns less metadata.

php

/* Wrong: returns all posts without pagination */
$posts = Post::get();
return response()->json($posts);

/* Right: returns paginated posts with metadata */
$posts = Post::paginate(10);
return response()->json($posts);

Quick Reference

Key points to remember when paginating Laravel API responses:

• Use Model::paginate(perPage) to get paginated results.
• Return the paginator directly as JSON for automatic metadata inclusion.
• Laravel reads the page query parameter automatically to fetch the correct page.
• Use simplePaginate() for lighter pagination without total count.

Key Takeaways

Use Laravel's built-in paginate() method on Eloquent queries to implement API pagination easily.

Return the paginator object directly as JSON to include data and pagination metadata automatically.

Ensure your frontend sends the page query parameter to navigate pages correctly.

Avoid using get() when you want paginated results; it returns all records without pagination.

Use simplePaginate() only if you do not need total count or last page info.