app/Http/
├── Controllers/Api/
│   ├── V1/PostController.php
│   └── V2/PostController.php
└── Resources/
    ├── V1/PostResource.php   ← "title", "body"
    └── V2/PostResource.php   ← "headline", "content", "author"

1. Put the version in the URL

   The simplest strategy is a URL prefix. Group each version's routes under v1 or v2. Combined with the automatic /api prefix, URLs become /api/v1/posts.

   
             use App\Http\Controllers\Api\V1;
             use App\Http\Controllers\Api\V2;
   
             Route::prefix('v1')->name('v1.')->group(function () {
                 Route::apiResource('posts', V1\PostController::class);
             });
   
             Route::prefix('v2')->name('v2.')->group(function () {
                 Route::apiResource('posts', V2\PostController::class);
             });
           

   ℹ️ Other strategies exist

   Some APIs read the version from a header like Accept: application/vnd.blog.v2+json. URL prefixes are easier to see, test with curl and cache, so start there.

2. Namespace controllers and resources by folder

   Generate classes straight into version folders. The folder becomes part of the namespace, so two classes can both be called PostController.

   
             php artisan make:controller Api/V2/PostController --api --model=Post
             php artisan make:resource V2/PostResource
           

   
             <?php
   
             namespace App\Http\Resources\V2;
   
             class PostResource extends \Illuminate\Http\Resources\Json\JsonResource
             {
                 public function toArray($request): array
                 {
                     return [
                         'id'       => $this->id,
                         'headline' => $this->title,     // renamed in v2
                         'content'  => $this->body,
                         'author'   => ['id' => $this->user_id, 'name' => $this->user->name],
                     ];
                 }
             }
           

   v1 clients keep getting title; v2 clients get headline. Nobody breaks.

3. Know Laravel's default JSON errors

   When a request sends Accept: application/json, Laravel already turns common exceptions into JSON. A missing model becomes a 404:

   
             curl -i http://127.0.0.1:8000/api/v1/posts/999 -H "Accept: application/json"
           

   
             { "message": "No query results for model [App\\Models\\Post] 999." }
           

   That message exposes your model class name, which you will tidy up in step 5. With APP_DEBUG=true you will also see the exception class and stack trace. Make sure it's false in production.

4. Validation errors come back as 422 JSON

   When $request->validate() or a Form Request fails on a JSON request, Laravel responds with 422. There's a summary message plus an errors object keyed by field.

   
             curl -X POST http://127.0.0.1:8000/api/v1/posts \
               -H "Accept: application/json" -H "Content-Type: application/json" \
               -H "Authorization: Bearer $TOKEN" \
               -d '{"title":""}'
           

   
             {
                 "message": "The title field is required. (and 1 more error)",
                 "errors": {
                     "title": ["The title field is required."],
                     "body": ["The body field is required."]
                 }
             }
           

   A client can show errors.title[0] right next to the title input.

5. Customise errors in bootstrap/app.php

   In Laravel 11/12, exception handling is configured with withExceptions. Two useful settings: always render JSON for api/* URLs, and give 404s a friendlier, consistent message.

   
             use Illuminate\Http\Request;
             use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
   
             ->withExceptions(function (Exceptions $exceptions) {
                 $exceptions->shouldRenderJsonWhen(
                     fn (Request $request) => $request->is('api/*') || $request->expectsJson()
                 );
   
                 $exceptions->render(function (NotFoundHttpException $e, Request $request) {
                     if ($request->is('api/*')) {
                         return response()->json([
                             'message' => 'Resource not found.',
                         ], 404);
                     }
                 });
             })
           

   Returning nothing from a render callback (as for web requests here) falls back to Laravel's default handling.

6. Throw meaningful errors yourself

   Use abort() for HTTP errors. It goes through the same handler, so the JSON stays consistent.

   
             abort_if($post->is_locked, 409, 'This post is locked for editing.');
             abort_unless($request->user()->can('delete', $post), 403);
           

   
             { "message": "This post is locked for editing." }
           

• Version with URL prefixes (/api/v1, /api/v2) and matching V1/V2 folders.
• Only breaking changes need a new version; adding fields is usually safe.
• Validation failures return 422 with message and a per-field errors object.
• Configure error rendering in bootstrap/app.php with withExceptions, shouldRenderJsonWhen and render.
• Keep APP_DEBUG=false in production so errors never leak stack traces.