Panduan Membuat REST API Laravel Menggunakan API Resource dan Form Request
Admin HijrahKreativa
Penulis
Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk
Admin HijrahKreativa
Penulis
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.
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:
{"data": ...}, endpoint lain langsung objek,{"error": true, "msg": "..."} dengan status 200,2026-10-19 08:00:00, kadang 19/10/2026,Hasil akhir: API v1 untuk modul iuran dan pengumuman dengan:
Autentikasi API dibahas di artikel berikutnya (Laravel Sanctum), dan versi API di API Versioning di Laravel.
| 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 |
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).
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 |
/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:
snake_case.2026-10-19T08:00:00+07:00.2026-10-19. Periode bulan: 2026-10.250000), bukan string berformat.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);
}
});
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:
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.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.
// 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.
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.
// 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
// 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.
// 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.
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.
| 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() |
Keamanan
auth:sanctum kecuali yang memang publik; otorisasi per data dengan Policy.per_page.Cache-Control: no-store untuk respons berisi data pribadi.Performa
whenLoaded()/whenCounted().cursorPaginate() untuk daftar panjang yang dipakai infinite scroll.Maintainability
V1), siap untuk versi berikutnya.code) untuk setiap error yang perlu ditangani klien.AssertableJson untuk setiap endpoint.| Komponen | Versi |
|---|---|
| Laravel | 13.x |
| PHP | 8.4 |
| Laravel Sanctum | 4.x |
| MySQL | 8.4 LTS |
| Pest | 4.x |
| Tanggal | 19 Oktober 2026 |
Sebelumnya
Membangun Laravel Admin Starter: Authentication, Permission, CRUD, Activity Log, dan Settings
Berikutnya
Laravel Sanctum: Cara Mengamankan API untuk Aplikasi Web dan Progressive Web App
Dokumen ini menjelaskan prosedur konfigurasi autentikasi SSH Key antara server Ubuntu dan GitHub untuk memungkinkan server melakukan operasi Git, seperti clone, pull, dan fetch tanpa menggunakan username dan password akun GitHub.
Peta jalan arsitektur dari satu server hingga banyak server: tahapan pertumbuhan dan sinyal kapan naik tahap, prinsip yang sebaiknya diterapkan sejak awal (stateless, asinkron, data ber-tenant), read replica, pengelolaan data yang terus tumbuh, degradasi yang anggun saat layanan bermasalah, feature...
Menyiapkan lingkungan uji yang jujur, mengukur satu endpoint dengan ApacheBench, mensimulasikan perilaku pengguna sungguhan dengan k6 (skenario, threshold, autentikasi token), menelusuri penyebab request lambat dengan Telescope, memantau server selama pengujian, serta menulis laporan hasil dan angga...
Bagaimana Octane membuat Laravel lebih cepat dengan mem-boot aplikasi sekali dan menyimpannya di memori, apa yang sebenarnya dipercepat (dan yang tidak), risiko kebocoran state antar-request yang wajib dipahami, cara memeriksa kode agar aman untuk Octane, pemasangan dengan FrankenPHP di production,...
03 Nov 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
HijrahKreativa
Kami balas secepatnya
Masuk dulu untuk chat dengan tim kami. Riwayat chat Anda tersimpan di akun.
Masuk