❌ Bad Practices When Building Laravel APIs

🚫 1. No API Versioning

Bad Practice:

GET /api/users

Why it’s bad:
Without versioning, any future changes will break existing clients.

✅ Best Practice:

Always version your APIs.

GET /api/v1/users

This allows you to iterate and evolve your API without breaking consumers.

🚫 2. Mixing Web and API Logic

Bad Practice:

Writing controllers that serve both web and API responses.

Why it’s bad:
It creates tight coupling, hard-to-test logic, and messy controllers.

✅ Best Practice:

Separate your API logic using dedicated API controllers:

php artisan make:controller Api/V1/UserController

Use the api.php routes file to isolate API-specific routes.

🚫 3. Returning Raw Models

Bad Practice:

Returning Eloquent models directly from the controller.

return User::all();

Why it’s bad:

This can expose sensitive fields and tightly couples your database structure to your API.

✅ Best Practice:

Use API Resource classes (introduced in Laravel 5.5+) for controlled, standardized responses.

return UserResource::collection(User::all());

🚫 4. Ignoring Request Validation

Bad Practice:

Using raw input from the request without validating.

✅ Best Practice:
Use Form Request classes:

php artisan make:request StoreUserRequest

Then in your controller:

public function store(StoreUserRequest $request) {
    // Safe, validated input
}

This makes validation reusable, testable, and clean.

🚫 5. Poor Error Handling

Bad Practice:
Returning unstructured or default Laravel error pages.

✅ Best Practice:

Use centralized exception handling in app/Exceptions/Handler.php and return consistent JSON responses with appropriate status codes:

{
  "message": "Resource not found",
  "status": 404
}

🚫 6. No Authentication or Using Session-Based Auth

Bad Practice:

Using web-based session authentication (Auth::user() without guards).

✅ Best Practice:

Use API tokens, Laravel Sanctum, or Laravel Passport for stateless authentication:

// Sanctum example
Route::middleware('auth:sanctum')->get('/user', fn (Request $request) => $request->user());

🚫 7. Business Logic in Controllers

Bad Practice:

Cluttering your controller with if-else and database logic.

✅ Best Practice:

Move complex logic into:

• Service classes
• Action classes
• Jobs/Listeners

This keeps controllers lean and focused on handling requests/responses.

🚫 8. Overfetching or N+1 Queries

Bad Practice:

return Post::all(); // And then access $post->comments in a loop

✅ Best Practice:
Use eager loading:

return Post::with('comments')->get();

🚫 9. Not Using Transformers or Resources

Bad Practice:
Returning inconsistent data structures.

✅ Best Practice:
Use JsonResource to control formatting, hide fields, and standardize outputs.

🚫 10. Ignoring OpenAPI/Swagger Documentation

Bad Practice:
No docs? You’re making it hard for your team or third-party developers.

✅ Best Practice:
Use packages like:

• knuckleswtf/scribe
• DarkaOnLine/L5-Swagger

They automate API documentation from routes and annotations.

💡 Final Thoughts

Building a robust Laravel API isn’t just about getting it to work. It’s about doing it right — using the framework’s best features to deliver clean, maintainable, and secure code.

Avoiding these bad practices and embracing best practices will save you (and your team) a lot of pain down the road.

If you found this helpful, feel free to share or drop a comment. Happy coding with Laravel! 🧱✨