app/
├── Http/
│   ├── Controllers/Api/
│   │   └── PostController.php   ← --api controller
│   └── Resources/
│       ├── PostResource.php     ← one post
│       └── PostCollection.php   ← optional custom list
routes/
└── api.php                      ← created by install:api

1. Install the API scaffolding

   New Laravel 11/12 apps don't include routes/api.php by default. One command creates it, installs Sanctum (for tokens, next lesson) and registers the file in bootstrap/app.php.

   
             php artisan install:api
           

   
             ->withRouting(
                 web: __DIR__.'/../routes/web.php',
                 api: __DIR__.'/../routes/api.php',   // added for you
                 commands: __DIR__.'/../routes/console.php',
                 health: '/up',
             )
           

   Every route in api.php automatically starts with /api and is stateless (no sessions or CSRF).

2. Register all CRUD routes at once

   Create a controller with the --api flag. It skips create and edit, because APIs don't serve HTML forms. Then wire it up with Route::apiResource.

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

   
             use App\Http\Controllers\Api\PostController;
   
             Route::apiResource('posts', PostController::class);
           

   
             GET|HEAD   api/posts ........... posts.index
             POST       api/posts ........... posts.store
             GET|HEAD   api/posts/{post} .... posts.show
             PUT|PATCH  api/posts/{post} .... posts.update
             DELETE     api/posts/{post} .... posts.destroy
           

3. Shape the output with an API Resource

   An API Resource is a class that converts one model into an array. Only the keys you return end up in the JSON.

   
             php artisan make:resource PostResource
           

   
             <?php
   
             namespace App\Http\Resources;
   
             use Illuminate\Http\Request;
             use Illuminate\Http\Resources\Json\JsonResource;
   
             class PostResource extends JsonResource
             {
                 public function toArray(Request $request): array
                 {
                     return [
                         'id'         => $this->id,
                         'title'      => $this->title,
                         'excerpt'    => str($this->body)->limit(80),
                         'author'     => $this->whenLoaded('user', fn () => $this->user->name),
                         'comments'   => $this->whenCounted('comments'),
                         'created_at' => $this->created_at->toIso8601String(),
                     ];
                 }
             }
           

   whenLoaded only includes the relation if you eager-loaded it, which helps avoid the N+1 problem.

4. Return resources with the right status codes

   Use PostResource::collection() for lists and new PostResource() for one item. Set 201 on create and 204 on delete.

   
             public function index()
             {
                 $posts = Post::with('user')->withCount('comments')->latest()->paginate(10);
   
                 return PostResource::collection($posts);
             }
   
             public function store(Request $request)
             {
                 $data = $request->validate([
                     'title' => ['required', 'string', 'max:255'],
                     'body'  => ['required', 'string'],
                 ]);
   
                 $post = $request->user()->posts()->create($data);
   
                 return (new PostResource($post))->response()->setStatusCode(201);
             }
   
             public function show(Post $post)
             {
                 return new PostResource($post->load('user'));   // 404 if not found
             }
   
             public function destroy(Post $post)
             {
                 $post->delete();
                 return response()->noContent();                  // 204
             }
           

   ℹ️ Validation is automatic

   If validate() fails on a JSON request, Laravel returns 422 with the errors. You'll see the exact shape in Versioning & Error Handling.

5. Read the JSON, including pagination meta

   Every resource response wraps data in a data key. When you pass a paginator, Laravel adds links and meta so clients can page through results.

   
             curl "http://127.0.0.1:8000/api/posts?page=2" -H "Accept: application/json"
           

   
             {
                 "data": [
                     { "id": 11, "title": "Queues 101", "excerpt": "Send emails later...",
                       "author": "Ada", "comments": 4, "created_at": "2026-10-01T08:00:00+00:00" }
                 ],
                 "links": {
                     "first": "http://127.0.0.1:8000/api/posts?page=1",
                     "last": "http://127.0.0.1:8000/api/posts?page=3",
                     "prev": "http://127.0.0.1:8000/api/posts?page=1",
                     "next": "http://127.0.0.1:8000/api/posts?page=3"
                 },
                 "meta": { "current_page": 2, "last_page": 3, "per_page": 10, "total": 27 }
             }
           

6. Customise the list with a ResourceCollection

   Need extra top-level data on a list? Create a ResourceCollection. It wraps many PostResource items and lets you add your own keys.

   
             php artisan make:resource PostCollection
           

   
             class PostCollection extends ResourceCollection
             {
                 public function toArray(Request $request): array
                 {
                     return [
                         'data'    => $this->collection,          // each item uses PostResource
                         'summary' => ['count_on_page' => $this->collection->count()],
                     ];
                 }
             }
           

   
             return new PostCollection(Post::latest()->paginate(10));
           

• php artisan install:api creates routes/api.php (auto /api prefix) and installs Sanctum.
• Route::apiResource registers index, store, show, update and destroy in one line.
• API Resources are an allow-list that turns a model into exactly the JSON you intend.
• Use ::collection() for lists; pass a paginator to get links and meta.
• Return 201 after creating and 204 (response()->noContent()) after deleting.