Featured image of post Insights on Developing RESTful APIs with Laravel

Insights on Developing RESTful APIs with Laravel

Developing APIs with Laravel: Routing, Authentication, Global Exception Handling, and More

Here are some insights I’ve gained while working with Laravel to develop RESTful APIs.

Getting Started

  • API Authentication: For public APIs, consider OAuth2.0; for private/internal APIs, token-based authentication (e.g., JWT) is often sufficient.
  • Versioning: Include an API version in routes for future scalability: 
    Route::prefix('v1')->group(function () {
    // Routes here
});
  • CORS Handling: Use the barryvdh/laravel-cors package for seamless cross-origin requests.

Sample API Endpoint

Example Code
Example Code

Authentication

  • Use jwt-auth for JWT-based authentication. Its 1.0+ version offers clear documentation.
  • Unlike Laravel’s default token-based authentication (which uses an api_token field), JWT stores encrypted user data within the token itself. Security relies on keeping your JWT secret key (generated via php artisan jwt:secret) confidential.

Routing Best Practices

  • Use Route::apiResource() for RESTful resource routing (replaces 5 individual routes).
  • Follow RESTful naming conventions: verbs, plural nouns, and clear semantics.
  • For multi-word route segments, choose either hyphens (-) or underscores (_). Laravel uses hyphens by default. Learn more: Routing Conventions.

Form Validation

  • Prefer Form Request Classes over inline validation for cleaner controllers. Example: 
    public function store(StoreUserRequest $request)
{
    // Validated data is automatically available
}

    Form Request Class
    Form Request Class

Data Transformation

  • Use Laravel’s Eloquent API Resources to format responses.
  • Return single resources with UserResource and collections with UserResource::collection().
  • Conditionally include relationships using whenLoaded(): 
    public function toArray($request)
{
    return [
        'id' => $this->id,
        'posts' => PostResource::collection($this->whenLoaded('posts')),
    ];
}

    API Resource Example
    API Resource Example

Consistent Response Format

Adopt a base controller to standardize API responses. Example structure:

protected function response($data, $status = 200)
{
    return response()->json([
        'data' => $data,
        'status' => $status,
    ], $status);
}

Exception Handling

Centralize exception handling in App\Exceptions\Handler:

public function render($request, Exception $exception)
{
    if ($exception instanceof UnauthorizedHttpException) {
        return response()->json(['error' => 'Invalid token'], 401);
    }
    if ($exception instanceof ValidationException) {
        return response()->json(['errors' => $exception->errors()], 422);
    }
    if ($exception instanceof ModelNotFoundException) {
        return response()->json(['error' => 'Resource not found'], 404);
    }
    return parent::render($request, $exception);
}

Exception Handling
Exception Handling

  • Simplify controller logic with findOrFail() or implicit model binding: 
    public function show(User $user)
{
    // Directly use $user
}

API Documentation

  • Use Swagger UI + Swagger Editor for interactive documentation.
  • Structure your OpenAPI spec in api.yaml/api.json and serve via Swagger UI.
    Swagger Setup
    Swagger Setup
  • Export specs from Swagger Editor and update your docs.
    Swagger Export
    Swagger Export

Custom Package: laravel-api-helper

I created a package to streamline common tasks:

  • Generate controllers and form requests via Artisan: 
    php artisan api:auth

    Package Demo
    Package Demo

  • Features: Base controller inheritance, standardized responses, and validation shortcuts.
    Learn more: laravel-api-helper.

Final Notes

  • Prioritize clear documentation and consistent error handling.
  • Keep controllers lean by delegating tasks to Form Requests, Resources, and dedicated classes.

References