Membuat API Laravel 13.x: Satu Alur dari Route hingga HTTP Test

Batas artikel: contoh berikut adalah alur dokumentasi untuk Laravel 13.x dan PHP 8.3+. Kode belum dijalankan dalam proyek Laravel bersih pada saat penulisan. Ia bukan bukti kesiapan produksi.

Jika Anda sudah memahami dasar PHP dan Laravel, cara yang lebih mudah untuk mempelajari API adalah mengikuti satu alur kecil sampai selesai: aktifkan routing API, buat endpoint publik, validasi input di controller atau Form Request, kembalikan response JSON, lindungi endpoint lain, lalu tulis HTTP test. Jangan memperluas contoh ini menjadi sistem produksi sebelum keputusan otorisasi, rate limiting, secrets, logging, deployment, dan versioning diperiksa.

1. Tetapkan alur kecil dan versi

Contoh memakai resource sederhana bernama tasks. Alurnya:

1. POST /api/tasks menerima judul tugas.
2. Laravel memvalidasi payload.
3. Endpoint mengembalikan JSON.
4. GET /api/tasks/private dijadikan contoh route terlindungi.
5. HTTP test memeriksa kontrak dasar endpoint.

Dokumentasi Laravel 13.x menyebut minimum PHP 8.3. Nama file, prefix, middleware, dan perilaku default di bawah adalah default terdokumentasi; konfigurasi aplikasi dapat mengubahnya.

2. Aktifkan routing API

Pada aplikasi Laravel 13.x, perintah berikut adalah jalur dokumentasi untuk mengaktifkan API routing:

php artisan install:api

Menurut dokumentasi routing Laravel 13.x, perintah ini memasang Sanctum dan membuat routes/api.php. Route di file tersebut bersifat stateless, memakai grup middleware api, dan menerima prefix /api secara otomatis. Prefix tersebut dapat diubah di bootstrap/app.php. Perintah ini adalah contoh dokumentasi; belum dieksekusi di lingkungan artikel ini.

Dengan demikian, route Route::post('/tasks', ...) di routes/api.php biasanya diakses sebagai POST /api/tasks, bukan POST /tasks.

3. Buat route dan controller

Buat controller dengan Artisan:

php artisan make:controller Api/TaskController

Lalu daftarkan route di routes/api.php:

<?php

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

Route::post('/tasks', [TaskController::class, 'store']);
Route::get('/tasks/private', [TaskController::class, 'privateIndex'])
    ->middleware('auth:sanctum');

Contoh controller berikut adalah ilustrasi berbasis dokumentasi, bukan hasil eksekusi. Ia belum menyimpan model ke database supaya fokus tetap pada alur request dan response.

<?php

namespace App\Http\Controllers\Api;

use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

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

        return response()->json([
            'data' => [
                'title' => $validated['title'],
            ],
        ], 201);
    }

    public function privateIndex(Request $request): JsonResponse
    {
        return response()->json([
            'message' => 'Endpoint terlindungi',
            'user_id' => $request->user()?->id,
        ]);
    }
}

Request::validate melanjutkan eksekusi ketika aturan lolos dan melempar ValidationException ketika gagal. Format respons kegagalan bergantung pada konteks request. Untuk request yang dianggap XHR, dokumentasi Laravel menjelaskan respons JSON dengan status 422; jangan mengubahnya menjadi klaim bahwa setiap kegagalan API selalu JSON 422 tanpa memeriksa request dan konfigurasi aplikasi.

Kapan memakai Form Request?

Untuk satu aturan singkat, validasi inline mudah dibaca. Saat aturan bertambah atau perlu dipakai ulang, pindahkan ke Form Request:

php artisan make:request StoreTaskRequest

Contoh bentuknya:

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StoreTaskRequest extends FormRequest
{
    /**
     * Demo ini sengaja memodelkan endpoint publik minimal.
     * Untuk resource terlindungi, delegasikan keputusan ke policy/business logic.
     */
    public function authorize(): bool
    {
        return true;
    }

    public function rules(): array
    {
        return [
            'title' => ['required', 'string', 'max:120'],
        ];
    }
}

authorize(): bool di atas hanya contoh eksplisit untuk alur demo yang sengaja publik; ia bukan keputusan akses untuk aplikasi nyata. Pada endpoint terlindungi, implementasikan keputusan berdasarkan user, resource, dan konteks aplikasi di policy atau business logic yang sesuai. Form Request memisahkan validasi dari otorisasi, tetapi tidak otomatis menyelesaikan otorisasi resource. Kode ini tetap ilustrasi berbasis dokumentasi dan belum dijalankan; route model, persistence, dan pesan error belum menjadi bagian alur minimal ini.

4. Pilih batas autentikasi dengan sadar

Route publik dan route terlindungi memiliki kebutuhan berbeda. auth:sanctum pada contoh hanya menunjukkan titik keputusan; middleware autentikasi tidak otomatis menyelesaikan otorisasi terhadap resource tertentu.

Sanctum mendukung SPA, aplikasi mobile, dan API token sederhana. Untuk SPA first-party, dokumentasinya membahas autentikasi berbasis cookie/session; token Bearer adalah salah satu jalur untuk penggunaan token API. Domain SPA, CSRF, CORS, abilities, dan kebijakan akses tetap perlu dikonfigurasi sesuai aplikasi.

Sanctum bukan jawaban universal. Jadikan Sanctum versus Passport sebagai keputusan terpisah:

• Pertimbangkan Sanctum ketika kebutuhan Anda adalah autentikasi SPA atau token API sederhana dan model aksesnya sesuai kemampuan Sanctum.
• Pertimbangkan Passport bila kebutuhan integrasi memang memerlukan protokol OAuth2 dan kompleksitas tersebut diterima oleh tim.
• Jangan memilih hanya dari nama package. Dokumentasikan klien, alur token, scopes/abilities, rotasi dan pencabutan, serta siapa yang boleh mengakses resource.

Artikel ini tidak memberikan tutorial Passport dan tidak menyimpulkan bahwa salah satu pilihan selalu lebih aman atau lebih cocok.

5. Tambahkan HTTP test yang memeriksa kontrak

Laravel menyediakan helper untuk menyimulasikan request di dalam aplikasi dan assertion untuk status, header, JSON, autentikasi, serta validasi. “Menyimulasikan” berarti contoh ini bukan pengujian jaringan eksternal.

Contoh test Pest berikut adalah dokumentasi-guided dan belum dijalankan:

<?php

use Tests\TestCase;

test('task endpoint menolak judul kosong', function () {
    $response = $this->postJson('/api/tasks', [
        'title' => '',
    ]);

    $response->assertStatus(422);
});

Status 422 di sini adalah kontrak yang ingin diuji untuk request JSON pada contoh validasi ini, bukan laporan bahwa test telah lulus. Tambahkan assertion terhadap bentuk error yang memang Anda tetapkan setelah kontrak API diputuskan. Jangan menyebut endpoint benar hanya karena satu assertion status ada.

Untuk route terlindungi, test perlu membuat user/factory yang sesuai dan mengautentikasi request dengan mekanisme yang dipakai aplikasi. Dokumentasi Sanctum menyediakan Sanctum::actingAs untuk konteks test; implementasinya tetap perlu disesuaikan dengan model dan abilities proyek.

Checklist sebelum menyebut API siap dipakai

Alur di atas belum production-ready. Sebelum deployment, buat pemeriksaan terpisah untuk:

• otorisasi per resource, bukan sekadar autentikasi;
• rate limiting yang sesuai risiko dan pola klien;
• secrets dan token yang tidak ditulis ke repository atau log;
• error contract yang konsisten tanpa membocorkan detail internal;
• logging dan pemantauan yang tidak memuat data sensitif;
• konfigurasi deployment, HTTPS, queue, database, dan cache;
• versioning endpoint dan kebijakan perubahan kontrak;
• test sukses, validasi gagal, autentikasi gagal, otorisasi gagal, dan kasus batas.

Checklist verifikasi operasional (belum dijalankan)

Sebelum menganggap alur ini terverifikasi, jalankan pemeriksaan berikut pada proyek target dan catat hasilnya:

• Pastikan environment memakai Laravel 13.x dan PHP 8.3+.
• Jalankan perintah Artisan yang dicantumkan, lalu pastikan routes/api.php, prefix /api, dan middleware route sesuai konfigurasi aplikasi.
• Kirim request valid dan invalid ke POST /api/tasks; periksa status serta bentuk JSON error yang benar-benar dikontrak.
• Pastikan StoreTaskRequest::authorize() sesuai keputusan akses; untuk resource nyata, periksa policy/business logic, bukan return true demo.
• Untuk route terlindungi, uji request tanpa autentikasi, dengan autentikasi, dan dengan user yang tidak berwenang.
• Jalankan HTTP test dengan fixture yang sesuai dan assertion terhadap response JSON, bukan status saja.

Checklist ini adalah rencana pemeriksaan, bukan laporan eksekusi. Contoh kode dan command di artikel tetap belum dijalankan dalam proyek Laravel bersih.

Kesimpulan

Satu alur API Laravel 13.x yang baik untuk latihan cukup dimulai dari install:api, route di routes/api.php, controller dengan validasi, satu route auth:sanctum, dan HTTP test yang bermakna. Prefix, middleware, dan respons validasi adalah perilaku terdokumentasi yang tetap bergantung pada konteks dan konfigurasi. Contoh di sini belum dieksekusi dan tidak menjamin keamanan atau kesiapan produksi.