Originally published at hafiz.dev
Building robust APIs used to mean wrestling with inconsistent responses, security vulnerabilities, and maintenance nightmares. I've spent the last seven years building SaaS products like StudyLab and ReplyGenius, and I've learned that Laravel API development requires more than just returning JSON from controllers.
Here's the thing, a poorly designed API will haunt you. Last year, I inherited a client project where the previous developer mixed response formats, skipped versioning, and hardcoded authentication logic. We spent three weeks just standardizing the responses before we could add new features.
In this guide, I'll walk you through the exact Laravel API patterns I use in production. You'll learn how to structure resources, implement secure authentication, handle versioning gracefully, and document everything so your team (and future you) doesn't want to throw their laptop out the window.
Why Laravel Excels at API Development
Laravel's built-in tools make REST API development surprisingly straightforward. You get API resources for consistent formatting, Sanctum for authentication, middleware for rate limiting, and Eloquent for database operations. Plus, Laravel 11 introduced even cleaner routing and improved validation.
But here's what most tutorials won't tell you: the real challenge isn't building an API, it's building one that scales. When StudyLab hit 10,000 users, our initial API design started showing cracks. Response times crept up. Authentication tokens expired unexpectedly. Rate limits were either too strict or too lenient.
That's when I learned that Laravel API best practices aren't just about clean code. They're about preventing the problems you can't see until you're already in production.
Setting Up Your Laravel API Foundation
Start with a fresh Laravel 11 installation. I prefer keeping API routes separate from web routes right from the beginning:
// routes/api.php
use Illuminate\Support\Facades\Route;
Route::prefix('v1')->group(function () {
// All v1 API routes here
});
Notice the v1 prefix? Don't skip versioning, even if you think you won't need it. I learned this the hard way. When ReplyGenius needed to change our response structure for mobile clients, we had no clean way to support both old and new formats simultaneously.
Configure your API in config/app.php:
'api' => [
'prefix' => 'api',
'middleware' => ['api'],
],
Additionally, update your CORS configuration in config/cors.php for production deployments:
'paths' => ['api/*'],
'allowed_origins' => [env('FRONTEND_URL')],
'allowed_methods' => ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
'allowed_headers' => ['Content-Type', 'Authorization'],
'supports_credentials' => true,
This prevents the classic "CORS error" that haunts every frontend developer working with APIs.
API Resources: Your Response Consistency Secret Weapon
Laravel API resources transform your Eloquent models into consistent JSON responses. They're like a contract between your backend and frontend, once you define the structure, it never changes unexpectedly.
Create a resource with Artisan:
php artisan make:resource UserResource
Here's how I structure resources in production:
namespace App\Http\Resources;
use Illuminate\Http\Resources\Json\JsonResource;
class UserResource extends JsonResource
{
public function toArray($request)
{
return [
'id' => $this->id,
'name' => $this->name,
'email' => $this->email,
'created_at' => $this->created_at->toISOString(),
'subscription' => new SubscriptionResource($this->whenLoaded('subscription')),
// Only include sensitive data for authenticated users
'api_token' => $this->when($request->user()?->id === $this->id, $this->api_token),
];
}
}
The whenLoaded() method prevents N+1 queries by only including relationships when they're eager loaded. The when() method conditionally includes fields, perfect for hiding sensitive data.
For collections, use resource collections:
php artisan make:resource UserCollection
namespace App\Http\Resources;
use Illuminate\Http\Resources\Json\ResourceCollection;
class UserCollection extends ResourceCollection
{
public function toArray($request)
{
return [
'data' => $this->collection,
'meta' => [
'total' => $this->total(),
'per_page' => $this->perPage(),
'current_page' => $this->currentPage(),
],
];
}
}
In your controller:
public function index()
{
$users = User::with('subscription')->paginate(15);
return new UserCollection($users);
}
public function show(User $user)
{
return new UserResource($user->load('subscription'));
}
This pattern gave me consistent responses across StudyLab's entire API. Frontend developers stopped asking "what format does this endpoint return?" because they all followed the same structure.
REST API Authentication with Laravel Sanctum
Laravel Sanctum provides lightweight authentication for SPAs and mobile apps. It's simpler than Passport (which uses OAuth2) and perfect for most use cases.
Install and configure Sanctum:
composer require laravel/sanctum
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
php artisan migrate
Add Sanctum's middleware to bootstrap/app.php in Laravel 11:
->withMiddleware(function (Middleware $middleware) {
$middleware->statefulApi();
})
Create a login endpoint that issues tokens:
namespace App\Http\Controllers\Api\V1;
use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;
use App\Models\User;
class AuthController extends Controller
{
public function login(Request $request)
{
$request->validate([
'email' => 'required|email',
'password' => 'required',
]);
$user = User::where('email', $request->email)->first();
if (!$user || !Hash::check($request->password, $user->password)) {
return response()->json([
'message' => 'Invalid credentials'
], 401);
}
// Revoke old tokens before creating new ones
$user->tokens()->delete();
$token = $user->createToken('api-token')->plainTextToken;
return response()->json([
'token' => $token,
'user' => new UserResource($user),
]);
}
public function logout(Request $request)
{
$request->user()->currentAccessToken()->delete();
return response()->json([
'message' => 'Logged out successfully'
]);
}
}
Protect routes with Sanctum middleware:
Route::prefix('v1')->group(function () {
Route::post('/login', [AuthController::class, 'login']);
Route::middleware('auth:sanctum')->group(function () {
Route::get('/user', [UserController::class, 'show']);
Route::post('/logout', [AuthController::class, 'logout']);
});
});
For ReplyGenius, I added token abilities to limit what each token can do:
$token = $user->createToken('api-token', ['posts:read', 'posts:create'])->plainTextToken;
// In routes
Route::middleware(['auth:sanctum', 'abilities:posts:create'])->post('/posts', [PostController::class, 'store']);
This is incredibly useful for third-party integrations where you want to limit API access.
API Versioning: Future-Proofing Your Endpoints
You might think "I'll add versioning when I need it." Don't make that mistake. When you need versioning, you need it yesterday, and retrofitting it into an existing API is painful.
Here's my preferred versioning strategy, URL-based versioning with route groups:
// routes/api.php
Route::prefix('v1')->name('v1.')->group(function () {
require base_path('routes/api/v1.php');
});
Route::prefix('v2')->name('v2.')->group(function () {
require base_path('routes/api/v2.php');
});
Create separate route files:
// routes/api/v1.php
Route::middleware('auth:sanctum')->group(function () {
Route::get('/users', [V1\UserController::class, 'index']);
});
// routes/api/v2.php
Route::middleware('auth:sanctum')->group(function () {
Route::get('/users', [V2\UserController::class, 'index']);
});
Organize controllers by version:
app/Http/Controllers/Api/
├── V1/
│ ├── UserController.php
│ └── PostController.php
└── V2/
├── UserController.php
└── PostController.php
When StudyLab needed to change how we returned quiz data, I created V2 controllers that inherited from V1:
namespace App\Http\Controllers\Api\V2;
use App\Http\Controllers\Api\V1\QuizController as V1QuizController;
class QuizController extends V1QuizController
{
public function show($id)
{
// V2-specific logic
$quiz = parent::show($id);
// Enhanced response format
return response()->json([
'quiz' => $quiz,
'analytics' => $this->getQuizAnalytics($id),
]);
}
}
This way, V1 users weren't affected, and V2 users got the enhanced format. We could deprecate V1 later on our own timeline.
Rate Limiting and Throttling
Laravel 11 simplified rate limiting significantly. Here's how to protect your API from abuse:
// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
$middleware->throttleApi();
})
The default is 60 requests per minute. For production APIs, I use custom rate limiters:
// app/Providers/AppServiceProvider.php
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Support\Facades\RateLimiter;
public function boot()
{
RateLimiter::for('api', function (Request $request) {
return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
});
RateLimiter::for('api-strict', function (Request $request) {
return Limit::perMinute(10)->by($request->user()?->id ?: $request->ip());
});
}
Apply different limits to different routes:
Route::middleware(['auth:sanctum', 'throttle:api'])->group(function () {
Route::get('/users', [UserController::class, 'index']);
});
Route::middleware(['auth:sanctum', 'throttle:api-strict'])->group(function () {
Route::post('/ai/generate', [AIController::class, 'generate']);
});
For ReplyGenius, AI generation endpoints cost money per request, so I set stricter limits there. This saved us hundreds of dollars in OpenAI costs from automated abuse.
You can also return custom rate limit headers:
return Limit::perMinute(60)
->by($request->user()?->id)
->response(function () {
return response()->json([
'message' => 'Too many requests. Please try again later.'
], 429);
});
Error Handling and Validation
Consistent error responses make your API predictable. Laravel's validation already returns good errors, but I customize them for better frontend integration:
// app/Exceptions/Handler.php
use Illuminate\Validation\ValidationException;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
public function render($request, Throwable $exception)
{
if ($request->is('api/*')) {
if ($exception instanceof ValidationException) {
return response()->json([
'message' => 'Validation failed',
'errors' => $exception->errors(),
], 422);
}
if ($exception instanceof NotFoundHttpException) {
return response()->json([
'message' => 'Resource not found',
], 404);
}
if ($exception instanceof \Illuminate\Auth\AuthenticationException) {
return response()->json([
'message' => 'Unauthenticated',
], 401);
}
return response()->json([
'message' => 'Server error',
'error' => config('app.debug') ? $exception->getMessage() : null,
], 500);
}
return parent::render($request, $exception);
}
For validation, use Form Requests to keep controllers clean:
php artisan make:request StorePostRequest
namespace App\Http\Requests;
use Illuminate\Foundation\Http\FormRequest;
class StorePostRequest extends FormRequest
{
public function authorize()
{
return true;
}
public function rules()
{
return [
'title' => 'required|string|max:255',
'content' => 'required|string',
'published_at' => 'nullable|date',
];
}
public function messages()
{
return [
'title.required' => 'Post title is required',
'content.required' => 'Post content cannot be empty',
];
}
}
Use it in your controller:
public function store(StorePostRequest $request)
{
$post = Post::create($request->validated());
return new PostResource($post);
}
Laravel automatically handles validation failures and returns 422 responses with error details.
API Documentation with Laravel Scribe
Documentation isn't optional for production APIs. I use Laravel Scribe, it generates beautiful docs automatically from your code annotations.
Install Scribe:
composer require --dev knuckleswtf/scribe
php artisan vendor:publish --tag=scribe-config
Document your endpoints with annotations:
/**
* Get all users
*
* Returns a paginated list of users with their subscriptions.
*
* @group User Management
* @authenticated
*
* @queryParam page integer The page number. Example: 1
* @queryParam per_page integer Results per page. Example: 15
*
* @response 200 {
* "data": [
* {
* "id": 1,
* "name": "John Doe",
* "email": "john@example.com",
* "created_at": "2025-01-15T10:00:00Z"
* }
* ],
* "meta": {
* "total": 100,
* "per_page": 15,
* "current_page": 1
* }
* }
*/
public function index()
{
$users = User::with('subscription')->paginate(15);
return new UserCollection($users);
}
Generate documentation:
php artisan scribe:generate
This creates interactive documentation at /docs. For StudyLab, I configured Scribe to include authentication examples and Postman collections automatically.
Testing Your Laravel API
Don't ship untested APIs. Here's my testing structure:
php artisan make:test Api/UserApiTest
namespace Tests\Feature\Api;
use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;
class UserApiTest extends TestCase
{
use RefreshDatabase;
public function test_user_can_login_with_valid_credentials()
{
$user = User::factory()->create([
'email' => 'test@example.com',
'password' => bcrypt('password'),
]);
$response = $this->postJson('/api/v1/login', [
'email' => 'test@example.com',
'password' => 'password',
]);
$response->assertStatus(200)
->assertJsonStructure([
'token',
'user' => ['id', 'name', 'email'],
]);
}
public function test_authenticated_user_can_access_protected_route()
{
$user = User::factory()->create();
$response = $this->actingAs($user, 'sanctum')
->getJson('/api/v1/user');
$response->assertStatus(200)
->assertJson([
'id' => $user->id,
'email' => $user->email,
]);
}
public function test_unauthenticated_user_cannot_access_protected_route()
{
$response = $this->getJson('/api/v1/user');
$response->assertStatus(401);
}
public function test_rate_limiting_works()
{
$user = User::factory()->create();
// Make 61 requests (assuming 60/minute limit)
for ($i = 0; $i < 61; $i++) {
$response = $this->actingAs($user, 'sanctum')
->getJson('/api/v1/users');
}
$response->assertStatus(429);
}
}
Run tests with:
php artisan test --filter=Api
I write tests for every new endpoint before marking it as productionready. This catches authentication bugs, validation issues, and response format problems early.
Performance Optimization Techniques
Fast APIs keep users happy. Here's what I do to keep response times under 200ms:
1. Eager Loading Relationships
// Bad - N+1 queries
$users = User::all();
foreach ($users as $user) {
echo $user->subscription->plan;
}
// Good - 2 queries total
$users = User::with('subscription')->all();
2. Caching Expensive Queries
public function index()
{
$users = Cache::remember('users.all', 3600, function () {
return User::with('subscription')->get();
});
return new UserCollection($users);
}
3. Database Indexing
Schema::table('users', function (Blueprint $table) {
$table->index('email');
$table->index('created_at');
});
4. Response Compression
Enable Gzip in your web server config. For API responses, this can reduce payload size by 70%.
5. Query Result Limiting
public function index(Request $request)
{
$perPage = min($request->get('per_page', 15), 100); // Max 100 results
$users = User::with('subscription')->paginate($perPage);
return new UserCollection($users);
}
For ReplyGenius, implementing these optimizations reduced our average API response time from 800ms to 200ms. Users noticed immediately, our Chrome extension felt snappier, and customer complaints about "slowness" disappeared.
Security Best Practices for Laravel APIs
Security isn't something you add later. Here's my checklist for every Laravel API I build:
1. Always Use HTTPS
Configure your .env:
APP_URL=https://yourdomain.com
SANCTUM_STATEFUL_DOMAINS=yourdomain.com
In production, redirect all HTTP to HTTPS in your web server configuration.
2. CSRF Protection for State-changing Endpoints
Sanctum handles this automatically for same-origin requests. For third-party integrations, use token-based auth instead of cookies.
3. SQL Injection Prevention
Laravel's query builder and Eloquent protect against SQL injection automatically. Never use raw queries with user input:
// Bad
DB::select("SELECT * FROM users WHERE email = '" . $request->email . "'");
// Good
User::where('email', $request->email)->first();
4. Mass Assignment Protection
Always define $fillable or $guarded in models:
class User extends Model
{
protected $fillable = ['name', 'email', 'password'];
// Or protect everything except specific fields
protected $guarded = ['id', 'is_admin'];
}
5. API Key Rotation
For long-lived API integrations, implement key rotation:
public function rotateApiKey(User $user)
{
$user->tokens()->where('name', 'api-key')->delete();
$token = $user->createToken('api-key', ['api-access'])->plainTextToken;
return response()->json(['api_key' => $token]);
}
6. Audit Logging
Track sensitive operations:
use Illuminate\Support\Facades\Log;
public function destroy(User $user)
{
Log::info('User deleted', [
'deleted_user_id' => $user->id,
'deleted_by' => auth()->id(),
'ip' => request()->ip(),
]);
$user->delete();
}
Common Laravel API Mistakes to Avoid
I've made every mistake in this section so you don't have to:
1. Returning Raw Eloquent Models
// Don't do this
return User::find($id);
// Do this
return new UserResource(User::find($id));
Raw models expose everything, including hidden fields if you're not careful. Resources give you control.
2. Inconsistent Response Formats
// Bad - different formats
Route::get('/users', fn() => User::all()); // Returns array
Route::get('/posts', fn() => ['data' => Post::all()]); // Returns object with data key
// Good - consistent format
Route::get('/users', fn() => new UserCollection(User::all()));
Route::get('/posts', fn() => new PostCollection(Post::all()));
3. Missing Pagination
Never return unbounded result sets. A client with 10,000 records will bring your API to its knees.
4. Ignoring HTTP Status Codes
Use the right codes:
- 200: Success
- 201: Created
- 204: No content (for deletions)
- 400: Bad request
- 401: Unauthenticated
- 403: Forbidden
- 404: Not found
- 422: Validation failed
- 429: Rate limited
- 500: Server error
5. No API Versioning
Start with v1 from day one. Trust me on this.
6. Exposing Stack Traces in Production
Set APP_DEBUG=false in production. Return generic error messages instead of stack traces.
7. Not Testing Edge Cases
Test these scenarios:
- Missing authentication
- Invalid JSON payloads
- SQL injection attempts
- Extremely large requests
- Concurrent request handling
- Rate limit behavior
Conclusion
Building production-ready Laravel APIs requires more than knowing how to return JSON. You need consistent resource formatting, robust authentication, sensible versioning, effective rate limiting, comprehensive documentation, and relentless testing.
The patterns I've shared come from building and maintaining APIs that handle millions of requests monthly across StudyLab, ReplyGenius, and client projects. Start with solid foundations, use API resources from day one, implement Sanctum authentication properly, version your endpoints, and document everything.
Your future self will thank you when you need to add new features, onboard new developers, or debug production issues at 2 AM.
The best Laravel API is one that's predictable, secure, fast, and well documented. Follow these patterns, adapt them to your needs, and you'll build APIs that developers actually enjoy working with.
Need help implementing these Laravel API best practices in your project? Let's work together: Contact me
Top comments (0)