Laravel · APIs
REST API Best Practices for Laravel Developers
REST API best practices for Laravel: resource naming, versioning, validation, API resources, authentication with Sanctum, rate limiting, errors and docs.
By Ehsan Ullah · Published · Last updated · 6 min read
What makes a good REST API?
A good REST API is predictable, secure and documented. Another developer, or a mobile app, should be able to guess how an endpoint behaves from its name, and get consistent responses and errors every time. These are the practices I use on Laravel APIs for mobile apps, Next.js frontends and third-party integrations.
1. Name resources consistently
- Use plural nouns:
/api/v1/orders,/api/v1/orders/{id}. - Let HTTP methods carry the action:
GET,POST,PUT/PATCH,DELETE. - Nest only one level deep:
/orders/{id}/items.
2. Version from day one
Prefix routes with /api/v1. When a breaking change is needed, add v2 and keep v1 running until clients move over.
3. Validate every input with Form Requests
Form Request classes keep controllers thin and return a consistent 422 response with field errors. Never trust input from apps or partners.
4. Shape output with API Resources
JsonResource classes decide exactly which fields leave your server, hide internal columns, and keep the response format stable even when the database changes.
5. Authenticate properly
- Use Laravel Sanctum for first-party SPAs and mobile apps; Passport when you need full OAuth2.
- Authorize with policies and gates, not ad-hoc
ifstatements. - Issue tokens with limited abilities for third-party integrations.
6. Return meaningful status codes and errors
| Code | Use |
|---|---|
| 200 / 201 | Success / created |
| 401 / 403 | Not authenticated / not allowed |
| 404 | Resource not found |
| 422 | Validation failed |
| 429 | Rate limit exceeded |
| 500 | Server error (log it, never leak details) |
Use one error format everywhere, for example { "message": "...", "errors": { ... } }.
7. Paginate, filter and limit
Paginate list endpoints, allow simple filters and sorting, and apply rate limiting with Laravel's RateLimiter to protect the server.
8. Make writes safe to retry
Wrap multi-step writes in database transactions. For payments and orders, accept an idempotency key so a retried request does not create a duplicate order.
9. Use queues and webhooks for slow work
Return quickly and process heavy tasks (emails, AI calls, courier bookings, Google Sheets sync) in queued jobs. Notify other systems with webhooks and retry on failure.
10. Document and test
Publish an OpenAPI spec or a Postman collection, and cover critical endpoints with feature tests. Documentation is part of the API, not an extra.
Need an API built or reviewed? See custom API development.