Week 15: Building REST APIs & Testing with Pest

1. API Routes

routes/api.php is a separate file from routes/web.php — every route inside it is automatically prefixed with /api and uses stateless authentication instead of sessions:

<?php

use App\Http\Controllers\Api\TaskController;
use Illuminate\Support\Facades\Route;

Route::middleware('auth:sanctum')->group(function () {
    Route::apiResource('tasks', TaskController::class);
});

apiResource is resource from Week 10, minus the create and edit routes — an API has no use for "show me a form," since the client renders its own UI and just needs data back.

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Models\Task;
use Illuminate\Http\Request;

class TaskController extends Controller
{
    public function index(Request $request)
    {
        return $request->user()->tasks()->with('tags')->get(); // eager-loaded, per Week 12
    }

    public function store(Request $request)
    {
        $validated = $request->validate([
            'title' => 'required|string|max:200',
        ]);

        return $request->user()->tasks()->create($validated);
    }
}

Returning an Eloquent model or collection directly from a controller auto-serializes to JSON — convenient, but as the next section covers, it also leaks every column on the model with no control over shape.

2. API Resources

Returning a model directly means every column — including ones like attachment_path or timestamps a client shouldn't need to care about — gets serialized as-is. An API Resource defines exactly what shape a model takes in a response, independent of its actual columns:

php artisan make:resource TaskResource

<?php

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class TaskResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'title' => $this->title,
            'is_done' => $this->is_done,
            'due_date' => $this->due_date?->toDateString(),
            'tags' => $this->whenLoaded('tags', fn () => $this->tags->pluck('name')),
            'created_at' => $this->created_at->toIso8601String(),
        ];
    }
}

<?php

use App\Http\Resources\TaskResource;

public function index(Request $request)
{
    $tasks = $request->user()->tasks()->with('tags')->get();
    return TaskResource::collection($tasks);
}

public function show(Task $task)
{
    $this->authorize('view', $task);
    return new TaskResource($task->load('tags'));
}

whenLoaded('tags', ...) only includes the tags key if the relationship was actually eager-loaded — this avoids accidentally triggering the N+1 problem from Week 12 by lazy-loading a relationship purely for serialization.

3. Versioning & Status Codes

Once an API has real clients, breaking its response shape breaks them too. Prefixing routes with a version lets you introduce breaking changes in v2 without touching existing v1 clients:

<?php

Route::prefix('v1')->middleware('auth:sanctum')->group(function () {
    Route::apiResource('tasks', \App\Http\Controllers\Api\V1\TaskController::class);
});

Return the correct HTTP status code for each outcome — clients depend on this, not just the response body:

• 200 OK — successful GET/PUT/PATCH
• 201 Created — successful POST that created a resource
• 204 No Content — successful DELETE, nothing to return
• 422 Unprocessable Entity — validation failed (Laravel's default for a failed validate() call on an API request)
• 403 Forbidden — authenticated, but not authorized (exactly what authorize() throws)
• 404 Not Found — resource doesn't exist (what findOrFail() throws)

<?php

public function store(Request $request)
{
    $task = $request->user()->tasks()->create($request->validate(['title' => 'required|max:200']));
    return (new TaskResource($task))->response()->setStatusCode(201);
}

4. Securing the API

With the token issued in Week 13, a client authenticates every request with a header — no session cookie involved at all:

curl -X GET http://localhost:8000/api/v1/tasks \
  -H "Authorization: Bearer 1|abc123..." \
  -H "Accept: application/json"

auth:sanctum on the route validates that header, resolves it to a User model, and populates $request->user() — from that point on, the rest of the controller code is identical whether the request came in via session or token.

5. Testing with Pest

Pest is a testing framework built on PHPUnit with a more expressive syntax — Laravel ships with it configured by default. A feature test exercises a full HTTP request through the application, database included:

php artisan make:test TaskApiTest --pest

<?php

use App\Models\Task;
use App\Models\User;

test('an authenticated user can list their own tasks', function () {
    $user = User::factory()->has(Task::factory()->count(3))->create();

    $response = $this->actingAs($user, 'sanctum')->getJson('/api/v1/tasks');

    $response->assertOk()->assertJsonCount(3);
});

test('a user cannot see another user\'s tasks', function () {
    $userA = User::factory()->has(Task::factory()->count(2))->create();
    $userB = User::factory()->has(Task::factory()->count(1))->create();

    $response = $this->actingAs($userA, 'sanctum')->getJson('/api/v1/tasks');

    $response->assertOk()->assertJsonCount(2); // only userA's own 2, not userB's
});

test('creating a task requires a title', function () {
    $user = User::factory()->create();

    $response = $this->actingAs($user, 'sanctum')->postJson('/api/v1/tasks', []);

    $response->assertStatus(422)->assertJsonValidationErrors('title');
});

This runs against a real (typically SQLite in-memory, for speed) test database, using the factories from Week 12 — exactly the kind of realistic, disposable data factories were built for. assertJsonCount(2) in the second test is doing real work: it's the automated proof that the ownership scoping from Week 13 actually holds, not just something that looked right in manual testing.

php artisan test
# or, directly:
./vendor/bin/pest

6. Hands-on Exercise

7. Knowledge Check

Four quick questions. Expand each to check your answer.