Laravel API Mistakes to Avoid

Build robust, clean, and secure Laravel APIs

Laravel makes API development easy and elegant. However, it’s also easy to make mistakes that lead to performance bottlenecks, inconsistent behavior, and security risks. This guide covers common Laravel API mistakes, complete with explanations and code examples to help you write better APIs.

Returning Raw Eloquent Models

What’s wrong?

return User::find($id);

This may expose:

• created_at, updated_at
• password
• remember_token

Better approach: Use API Resources

php artisan make:resource UserResource

public function store(Request $request, UserService $userService)
{
    $user = $userService->create($request->all());
    return new UserResource($user);
}

public function toArray($request)
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
    ];
}

return new UserResource(User::find($id));

Mixing Business Logic in Controllers

What’s wrong?

Controllers should handle HTTP requests—not business logic. Keeping logic here makes code hard to test and maintain.

public function store(Request $request)
{
    $user = User::create($request->all());
    Mail::to($user->email)->send(new WelcomeMail($user));
}

Better approach: Delegate to a Service class

// app/Services/UserService.php
class UserService {
    public function create(array $data)
    {
        $user = User::create($data);
        Mail::to($user->email)->send(new WelcomeMail($user));
        return $user;
    }
}

// UserController.php
public function store(Request $request, UserService $userService)
{
    $user = $userService->create($request->all());
    return new UserResource($user);
}

No API Versioning

What’s wrong?

APIs change. Without versioning, existing clients may break when you update your code.

Route::get('/users', [UserController::class, 'index']);

Use versioned route groups:

Route::prefix('v1')->group(function () {
    Route::get('/users', [App\Http\Controllers\API\V1\UserController::class, 'index']);
});
You can later add:

Route::prefix('v2')->group(function () {
    Route::get('/users', [App\Http\Controllers\API\V2\UserController::class, 'index']);
});

Inline Validation

What’s wrong?

```php
$request->validate([
    'email' => 'required|email',
]);

Better approach: Delegate to a Service class

Use `FormRequest`:

bash
php artisan make:request StoreUserRequest


php
// StoreUserRequest.php
public function rules()
{
    return [
        'email' => 'required|email',
    ];
}

php
// Controller
public function store(StoreUserRequest $request)
{
    // Validated automatically
}

Conclusion

Writing clean, efficient, and scalable APIs with Laravel goes far beyond making your code “work.” It requires attention to structure, clarity, and long-term maintainability. The mistakes outlined in this guide like returning raw models, mixing logic in controllers, or skipping API versioning are all common, but avoidable. By implementing best practices such as using API Resources, Service classes, Form Requests, eager loading, and proper exception handling, you can significantly improve the quality and reliability of your Laravel APIs. These changes not only enhance security and performance but also make your codebase easier to maintain, test, and extend as your project grows.