Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk

Blog / REST API, Integrasi & Automation / Panduan Membuat REST API Larav...
REST API, Integrasi & Automation

Panduan Membuat REST API Laravel Menggunakan API Resource dan Form Request

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
14 min read
10 views

Membangun REST API yang konsisten dan mudah dipakai klien: konvensi URL dan status HTTP, Form Request untuk validasi, API Resource untuk bentuk respons, format error yang seragam, pagination dan filter, header yang tepat, serta test yang menjaga kontrak API tetap stabil.

Overview

API yang dipakai aplikasi mobile atau PWA warga RW akan diakses oleh kode yang tidak Anda kendalikan sepenuhnya. Setiap ketidakkonsistenan menjadi pekerjaan tambahan bagi tim frontend:

  • satu endpoint mengembalikan {"data": ...}, endpoint lain langsung objek,
  • error validasi berformat 422 Laravel, tetapi error bisnis berupa {"error": true, "msg": "..."} dengan status 200,
  • tanggal kadang 2026-10-19 08:00:00, kadang 19/10/2026,
  • nama field berubah karena kolom database diganti, dan aplikasi mobile versi lama rusak,
  • error 500 menampilkan stack trace HTML di production.

Hasil akhir: API v1 untuk modul iuran dan pengumuman dengan:

  • konvensi URL, metode, dan status HTTP yang konsisten,
  • Form Request untuk validasi dan otorisasi,
  • API Resource sebagai kontrak respons (terpisah dari struktur database),
  • format error seragam untuk semua jenis kegagalan,
  • pagination, filter, dan sorting lewat query string,
  • test kontrak API dengan Pest.

Autentikasi API dibahas di artikel berikutnya (Laravel Sanctum), dan versi API di API Versioning di Laravel.

Prerequisites

Komponen Versi
PHP 8.3+ (disarankan 8.4)
Laravel 13.x
Laravel Sanctum 4.x (dipasang lewat install:api)
Database MySQL 8.0+ / PostgreSQL 15+
Testing Pest 4
Alat uji manual Bruno, Postman, atau HTTPie

Step-by-step Tutorial

Langkah 1: Siapkan Route API

Proyek Laravel 13 baru tidak menyertakan routes/api.php secara bawaan. Pasang dengan:

php artisan install:api

Perintah ini membuat routes/api.php, memasang Laravel Sanctum, dan mendaftarkan route API dengan prefiks /api serta grup middleware api (tanpa session dan CSRF).

Langkah 2: Tetapkan Konvensi Sejak Awal

Tulis konvensi ini di dokumentasi API dan patuhi di setiap endpoint.

URL dan metode:

Aksi Metode URL Status sukses
Daftar GET /api/v1/pengumuman 200
Detail GET /api/v1/pengumuman/{id} 200
Buat POST /api/v1/pengumuman 201 + header Location
Ubah sebagian PATCH /api/v1/pengumuman/{id} 200
Hapus DELETE /api/v1/pengumuman/{id} 204 tanpa body
Aksi khusus POST /api/v1/iuran/{id}/pembayaran 201 / 202
  • Nama sumber daya berupa kata benda jamak atau kolektif, huruf kecil, dipisah tanda hubung.
  • Aksi yang bukan CRUD dimodelkan sebagai sub-sumber daya (/iuran/{id}/pembayaran), bukan kata kerja (/bayarIuran).

Status error:

Status Kapan
400 Request tidak bisa dipahami (JSON rusak)
401 Tidak terautentikasi
403 Terautentikasi tetapi tidak berizin
404 Data tidak ada atau tidak boleh diketahui keberadaannya
409 Konflik status (misalnya iuran sudah dibayar)
422 Validasi gagal
429 Terlalu banyak request
500 Kesalahan server (tanpa detail teknis)

Format data:

  • Nama field snake_case.
  • Tanggal-waktu dalam ISO 8601 dengan zona waktu: 2026-10-19T08:00:00+07:00.
  • Tanggal saja: 2026-10-19. Periode bulan: 2026-10.
  • Uang sebagai integer rupiah (250000), bukan string berformat.
  • ID sebagai string bila memakai ULID/UUID, atau integer bila auto increment; konsisten di semua endpoint.

Langkah 3: Format Error yang Seragam

Pastikan semua request ke /api/* selalu dijawab dengan JSON, termasuk error 404 dan 500:

// bootstrap/app.php
use Illuminate\Http\Request;
use Illuminate\Foundation\Configuration\Exceptions;
use Symfony\Component\HttpKernel\Exception\HttpException;

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->shouldRenderJsonWhen(fn (Request $request) => $request->is('api/*') || $request->expectsJson());

    $exceptions->render(function (\App\Exceptions\BusinessRuleException $e, Request $request) {
        if ($request->is('api/*')) {
            return response()->json([
                'message' => $e->getMessage(),
                'code'    => $e->errorCode,
            ], $e->status);
        }
    });
})
// app/Exceptions/BusinessRuleException.php
namespace App\Exceptions;

use RuntimeException;

class BusinessRuleException extends RuntimeException
{
    public function __construct(
        string $message,
        public readonly string $errorCode = 'business_rule',
        public readonly int $status = 409,
    ) {
        parent::__construct($message);
    }
}

Hasilnya, klien selalu menerima struktur yang sama:

// 422 validasi (format bawaan Laravel)
{
  "message": "Judul wajib diisi. (dan 1 kesalahan lainnya)",
  "errors": { "judul": ["Judul wajib diisi."], "isi": ["Isi wajib diisi."] }
}

// 409 aturan bisnis
{ "message": "Iuran periode 2026-10 sudah dibayar.", "code": "iuran_sudah_dibayar" }

// 404
{ "message": "Data tidak ditemukan." }

Kode error (code) memberi klien sesuatu yang stabil untuk diperiksa, karena teks message bisa berubah atau diterjemahkan. Dengan APP_DEBUG=false, error 500 hanya berisi {"message": "Server Error"}, tanpa stack trace.

Ubah pesan 404 bawaan agar tidak membocorkan nama model:

$exceptions->render(function (\Symfony\Component\HttpKernel\Exception\NotFoundHttpException $e, Request $request) {
    if ($request->is('api/*')) {
        return response()->json(['message' => 'Data tidak ditemukan.'], 404);
    }
});

Langkah 4: API Resource sebagai Kontrak Respons

php artisan make:resource V1/PengumumanResource
// app/Http/Resources/V1/PengumumanResource.php
namespace App\Http\Resources\V1;

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

class PengumumanResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id'            => $this->id,
            'judul'         => $this->judul,
            'ringkasan'     => str($this->isi)->stripTags()->limit(160)->toString(),
            'isi'           => $this->when($request->routeIs('api.v1.pengumuman.show'), $this->isi),
            'penting'       => (bool) $this->penting,
            'terbit_pada'   => $this->terbit_pada?->toIso8601String(),
            'penulis'       => $this->whenLoaded('penulis', fn () => [
                'id'   => $this->penulis->id,
                'nama' => $this->penulis->name,
            ]),
            'jumlah_dibaca' => $this->whenCounted('pembaca'),
            'tautan'        => [
                'self' => route('api.v1.pengumuman.show', $this->resource),
            ],
        ];
    }
}

Prinsip API Resource:

  • Resource adalah kontrak, bukan cerminan tabel. Kolom database bisa diganti nama tanpa mengubah API, cukup ubah pemetaannya di sini.
  • Jangan pernah return $model; dari controller API. Model mengirim semua kolom yang tidak $hidden, termasuk kolom baru yang ditambahkan kemudian.
  • whenLoaded() dan whenCounted() mencegah N+1 dan hanya menampilkan relasi yang sengaja dimuat.
  • Field berat (isi lengkap) hanya muncul di endpoint detail.

Untuk koleksi, Laravel otomatis menambahkan links dan meta pagination:

return PengumumanResource::collection($pengumuman);   // $pengumuman hasil paginate()
{
  "data": [ { "id": 41, "judul": "Kerja bakti Minggu", "...": "..." } ],
  "links": { "first": "...?page=1", "last": "...?page=5", "prev": null, "next": "...?page=2" },
  "meta":  { "current_page": 1, "per_page": 15, "total": 68, "last_page": 5, "...": "..." }
}

Tambahkan informasi tingkat koleksi bila perlu:

return PengumumanResource::collection($pengumuman)->additional([
    'meta' => ['belum_dibaca' => $request->user()->pengumumanBelumDibaca()->count()],
]);

Laravel 13 juga menyediakan dukungan resource yang mengikuti spesifikasi JSON:API. Gunakan bila tim atau klien Anda memang memakai spesifikasi tersebut; untuk API internal, resource biasa seperti di atas sudah cukup dan lebih sederhana.

Langkah 5: Form Request untuk Validasi API

// app/Http/Requests/Api/V1/StorePengumumanRequest.php
namespace App\Http\Requests\Api\V1;

use App\Models\Pengumuman;
use Illuminate\Foundation\Http\FormRequest;

class StorePengumumanRequest extends FormRequest
{
    public function authorize(): bool
    {
        return $this->user()->can('create', Pengumuman::class);
    }

    public function rules(): array
    {
        return [
            'judul'       => ['required', 'string', 'min:5', 'max:150'],
            'isi'         => ['required', 'string', 'max:20000'],
            'penting'     => ['sometimes', 'boolean'],
            'terbit_pada' => ['nullable', 'date', 'after_or_equal:now'],
            'rt_ids'      => ['sometimes', 'array', 'max:50'],
            'rt_ids.*'    => ['integer', 'distinct', 'exists:rukun_tetangga,id'],
        ];
    }
}
// app/Http/Requests/Api/V1/UpdatePengumumanRequest.php
public function authorize(): bool
{
    return $this->user()->can('update', $this->route('pengumuman'));
}

public function rules(): array
{
    return [
        'judul'       => ['sometimes', 'string', 'min:5', 'max:150'],
        'isi'         => ['sometimes', 'string', 'max:20000'],
        'penting'     => ['sometimes', 'boolean'],
        'terbit_pada' => ['sometimes', 'nullable', 'date'],
    ];
}

sometimes membuat PATCH benar-benar parsial: hanya field yang dikirim yang divalidasi dan diubah. Karena request API tidak memiliki "halaman sebelumnya", Laravel otomatis mengembalikan 422 JSON alih-alih redirect, selama klien mengirim header Accept: application/json atau route berada di api/* dengan konfigurasi Langkah 3.

Langkah 6: Controller API

php artisan make:controller Api/V1/PengumumanController --api --model=Pengumuman
// app/Http/Controllers/Api/V1/PengumumanController.php
namespace App\Http\Controllers\Api\V1;

use App\Http\Controllers\Controller;
use App\Http\Requests\Api\V1\{StorePengumumanRequest, UpdatePengumumanRequest};
use App\Http\Resources\V1\PengumumanResource;
use App\Models\Pengumuman;
use App\Services\PengumumanService;
use Illuminate\Http\{JsonResponse, Request, Response};
use Illuminate\Support\Facades\Gate;
use Illuminate\Validation\Rule;

class PengumumanController extends Controller
{
    public function __construct(private readonly PengumumanService $service) {}

    public function index(Request $request)
    {
        $q = $request->validate([
            'cari'     => ['nullable', 'string', 'min:2', 'max:50'],
            'penting'  => ['nullable', 'boolean'],
            'sort'     => ['nullable', Rule::in(['terbit_pada', '-terbit_pada', 'judul'])],
            'per_page' => ['nullable', 'integer', 'between:1,50'],
        ]);

        $sort = $q['sort'] ?? '-terbit_pada';

        $pengumuman = Pengumuman::query()
            ->terbitUntuk($request->user())                 // scope: sudah terbit & sesuai RT pengguna
            ->with('penulis:id,name')
            ->when($q['cari'] ?? null, fn ($x, $c) => $x->whereFullText(['judul', 'isi'], $c))
            ->when(isset($q['penting']), fn ($x) => $x->where('penting', (bool) $q['penting']))
            ->orderBy(ltrim($sort, '-'), str_starts_with($sort, '-') ? 'desc' : 'asc')
            ->orderByDesc('id')
            ->paginate($q['per_page'] ?? 15)
            ->withQueryString();

        return PengumumanResource::collection($pengumuman);
    }

    public function store(StorePengumumanRequest $request): JsonResponse
    {
        $pengumuman = $this->service->buat($request->validated(), $request->user());

        return (new PengumumanResource($pengumuman->load('penulis')))
            ->response()
            ->setStatusCode(Response::HTTP_CREATED)
            ->header('Location', route('api.v1.pengumuman.show', $pengumuman));
    }

    public function show(Pengumuman $pengumuman): PengumumanResource
    {
        Gate::authorize('view', $pengumuman);

        return new PengumumanResource($pengumuman->load('penulis:id,name')->loadCount('pembaca'));
    }

    public function update(UpdatePengumumanRequest $request, Pengumuman $pengumuman): PengumumanResource
    {
        $pengumuman = $this->service->ubah($pengumuman, $request->validated());

        return new PengumumanResource($pengumuman->load('penulis:id,name'));
    }

    public function destroy(Pengumuman $pengumuman): Response
    {
        Gate::authorize('delete', $pengumuman);

        $pengumuman->delete();

        return response()->noContent();
    }
}

Controller tetap tipis: validasi di Form Request, logika di service (artikel Cara Membangun CRUD Laravel yang Terstruktur), dan bentuk respons di Resource. Nilai sort aman dipakai di orderBy karena sudah divalidasi dengan daftar putih.

Langkah 7: Route

// routes/api.php
use App\Http\Controllers\Api\V1;

Route::prefix('v1')->name('api.v1.')->middleware(['auth:sanctum', 'throttle:api'])->group(function () {
    Route::apiResource('pengumuman', V1\PengumumanController::class)
        ->parameters(['pengumuman' => 'pengumuman']);

    Route::get('iuran', [V1\IuranController::class, 'index'])->name('iuran.index');
    Route::get('iuran/{iuran}', [V1\IuranController::class, 'show'])->name('iuran.show');
    Route::post('iuran/{iuran}/pembayaran', [V1\PembayaranController::class, 'store'])->name('iuran.pembayaran.store');
});

Laravel menentukan nama parameter apiResource dengan mengubah nama sumber daya ke bentuk tunggal menurut aturan bahasa Inggris. Untuk kata Indonesia hasilnya bisa aneh, misalnya kas menjadi {ka}. Menyebutkan parameters() secara eksplisit membuat nama parameter selalu sesuai dengan argumen di controller.

php artisan route:list --path=api/v1

Langkah 8: Aksi Non-CRUD dan Error Bisnis

// app/Http/Controllers/Api/V1/PembayaranController.php
public function store(Request $request, Iuran $iuran, CatatPembayaranIuran $catat): JsonResponse
{
    Gate::authorize('bayar', $iuran);

    if ($iuran->dibayar_pada) {
        throw new BusinessRuleException(
            "Iuran periode {$iuran->periode} sudah dibayar.",
            'iuran_sudah_dibayar',
        );
    }

    $pembayaran = $catat->mulai($iuran, $request->user());   // membuat transaksi payment gateway

    return (new PembayaranResource($pembayaran))->response()->setStatusCode(201);
}

Klien dapat menangani 409 + code: iuran_sudah_dibayar secara khusus, misalnya dengan memuat ulang data iuran.

Langkah 9: Header yang Membantu Klien

// app/Http/Middleware/ApiHeaders.php
public function handle(Request $request, Closure $next): Response
{
    $response = $next($request);

    $response->headers->set('Content-Type', 'application/json; charset=utf-8', false);
    $response->headers->set('Cache-Control', 'no-store', false);   // data pribadi: jangan di-cache perantara
    $response->headers->set('X-Request-Id', $request->attributes->get('request_id', (string) Str::uuid()));

    return $response;
}

X-Request-Id memudahkan dukungan: klien menyertakan ID ini saat melapor masalah, dan Anda bisa mencarinya di log. Catat ID yang sama di konteks log:

// middleware yang berjalan lebih awal
$id = $request->header('X-Request-Id') ?: (string) Str::uuid();
$request->attributes->set('request_id', $id);
Log::withContext(['request_id' => $id]);

Atur rate limiter api di AppServiceProvider:

RateLimiter::for('api', fn (Request $request) =>
    Limit::perMinute(120)->by($request->user()?->id ?: $request->ip()));

Respons yang terkena limit otomatis mendapat status 429 dan header Retry-After.

Langkah 10: Test Kontrak API

Test API sebaiknya memeriksa bentuk respons, bukan hanya status, karena bentuk itulah yang diandalkan klien.

// tests/Feature/Api/V1/PengumumanApiTest.php
use Illuminate\Testing\Fluent\AssertableJson;
use Laravel\Sanctum\Sanctum;

beforeEach(function () {
    $this->seed(\Database\Seeders\RolePermissionSeeder::class);
    $this->pengurus = User::factory()->create()->assignRole('pengurus');
});

it('mengembalikan daftar dengan struktur kontrak', function () {
    Pengumuman::factory()->count(3)->terbit()->create();
    Sanctum::actingAs($this->pengurus);

    $this->getJson('/api/v1/pengumuman')
        ->assertOk()
        ->assertJson(fn (AssertableJson $json) => $json
            ->has('data', 3, fn ($item) => $item
                ->whereType('id', 'integer')
                ->whereType('judul', 'string')
                ->whereType('ringkasan', 'string')
                ->whereType('penting', 'boolean')
                ->where('terbit_pada', fn ($v) => str_contains($v, 'T'))
                ->missing('isi')                          // isi lengkap hanya di detail
                ->etc())
            ->has('links')
            ->has('meta.total'));
});

it('membuat pengumuman dan mengembalikan 201 dengan Location', function () {
    Sanctum::actingAs($this->pengurus);

    $res = $this->postJson('/api/v1/pengumuman', ['judul' => 'Kerja bakti Minggu', 'isi' => 'Kumpul pukul 07.00 di pos.'])
        ->assertCreated()
        ->assertJsonPath('data.judul', 'Kerja bakti Minggu');

    expect($res->headers->get('Location'))->toEndWith('/api/v1/pengumuman/'.$res->json('data.id'));
});

it('mengembalikan 422 dengan format errors', function () {
    Sanctum::actingAs($this->pengurus);

    $this->postJson('/api/v1/pengumuman', [])
        ->assertUnprocessable()
        ->assertJsonValidationErrors(['judul', 'isi']);
});

it('mengembalikan JSON 404 tanpa nama model', function () {
    Sanctum::actingAs($this->pengurus);

    $this->getJson('/api/v1/pengumuman/999999')
        ->assertNotFound()
        ->assertExactJson(['message' => 'Data tidak ditemukan.']);
});

it('mengembalikan 409 dengan kode error untuk iuran yang sudah dibayar', function () {
    $warga = User::factory()->for(Keluarga::factory())->create()->assignRole('warga');
    $iuran = Iuran::factory()->for($warga->keluarga)->create(['dibayar_pada' => now()]);
    Sanctum::actingAs($warga);

    $this->postJson("/api/v1/iuran/{$iuran->id}/pembayaran")
        ->assertStatus(409)
        ->assertJsonPath('code', 'iuran_sudah_dibayar');
});

it('menolak request tanpa autentikasi dengan 401 JSON', function () {
    $this->getJson('/api/v1/pengumuman')->assertUnauthorized()->assertJsonStructure(['message']);
});

Test ini berfungsi sebagai dokumentasi kontrak. Bila seseorang mengubah nama field di Resource, test akan gagal sebelum aplikasi mobile ikut rusak.

Troubleshooting

Error / Gejala Penyebab Solusi
Error validasi dikembalikan sebagai redirect 302 Klien tidak mengirim Accept: application/json Kirim header tersebut, atau aktifkan shouldRenderJsonWhen untuk api/*
routes/api.php tidak ada / route API 404 API belum dipasang di Laravel 11+ php artisan install:api
Route model binding gagal, parameter bernama aneh (misalnya {ka} untuk kas) Singularisasi bahasa Inggris pada apiResource Gunakan ->parameters(['kas' => 'kas'])
Respons 500 berisi HTML Exception tidak dirender sebagai JSON shouldRenderJsonWhen di bootstrap/app.php
Kolom sensitif ikut terkirim Controller mengembalikan model langsung Selalu bungkus dengan API Resource
meta/links pagination tidak muncul Resource collection dibuat dari get() Gunakan paginate() / cursorPaginate()
Tanggal tanpa zona waktu Memformat dengan format('Y-m-d H:i:s') Gunakan toIso8601String()
N+1 query di endpoint daftar Relasi diakses di Resource tanpa eager load with() di controller + whenLoaded() di Resource
429 Too Many Attempts saat pengujian Rate limiter aktif Naikkan limit di lingkungan test atau RateLimiter::clear()

Best Practices

Keamanan

  • Semua endpoint di belakang auth:sanctum kecuali yang memang publik; otorisasi per data dengan Policy.
  • Kembalikan data lewat Resource saja; jangan pernah model mentah.
  • Pengurutan dan filter lewat daftar putih; batasi per_page.
  • Cache-Control: no-store untuk respons berisi data pribadi.
  • Error 500 tanpa detail teknis di production.

Performa

  • Eager load relasi dan pakai whenLoaded()/whenCounted().
  • Field berat hanya di endpoint detail.
  • Gunakan cursorPaginate() untuk daftar panjang yang dipakai infinite scroll.
  • Rate limit per pengguna untuk menjaga server dari klien yang salah konfigurasi.

Maintainability

  • Konvensi URL, status, dan format data ditulis dan dipatuhi di semua endpoint.
  • Resource dan Request dikelompokkan per versi (V1), siap untuk versi berikutnya.
  • Kode error bisnis yang stabil (code) untuk setiap error yang perlu ditangani klien.
  • Test kontrak dengan AssertableJson untuk setiap endpoint.
  • Hasilkan dokumentasi API otomatis (artikel Membuat Dokumentasi API dan Panduan Instalasi).

Related Articles

Last Tested

Komponen Versi
Laravel 13.x
PHP 8.4
Laravel Sanctum 4.x
MySQL 8.4 LTS
Pest 4.x
Tanggal 19 Oktober 2026

Bagikan artikel:

Artikel lainnya