Panduan Laravel API Resources untuk Response yang Konsisten di Tim

Setiap developer yang pernah bekerja dalam tim pasti pernah mengalami momen ini: frontend developer datang sambil bawa screenshot Postman dan bilang, "Mas, kok format response-nya berubah lagi?"

Masalah ini lebih umum dari yang disangka. Dan dampaknya tidak kecil.

Masalah Inkonsistensi Response API dan Dampaknya ke Tim Frontend

Bayangkan skenario ini: satu endpoint mengembalikan user_id, endpoint lain mengembalikan id, dan endpoint ketiga mengembalikan userId.

Mobile developer harus nulis tiga kondisi berbeda hanya untuk satu field yang sama.

Belum lagi kalau response sukses kadang pakai data, kadang langsung object, kadang array. Error kadang pakai message, kadang error, kadang errors dalam bentuk array.

Ini bukan masalah teknis kecil. Ini adalah masalah kolaborasi yang nyata.

Konsekuensi yang sering terjadi:

• Frontend developer harus cek source code backend setiap kali ada field baru
• Bug production karena asumsi format yang berbeda antara developer
• Waktu debugging yang seharusnya bisa dipakai untuk fitur baru
• Dokumentasi API yang selalu out of date karena tidak ada standar

Laravel sebenarnya sudah menyediakan solusi elegan untuk masalah ini: API Resources.

Membuat API Resource dan Collection untuk Transformasi Data yang Rapi

Laravel API Resources adalah layer transformasi antara Eloquent model dan JSON response yang dikirim ke client.

Konsepnya sederhana: bukan langsung return model, tapi lewat "filter" dulu yang menentukan field apa yang keluar dan dalam format seperti apa.

Membuat Resource Pertama

Jalankan perintah Artisan berikut:

php artisan make:resource UserResource
php artisan make:resource UserCollection

File UserResource.php akan dibuat di app/Http/Resources/. Isi defaultnya seperti ini:

<?php

namespace App\Http\Resources;

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

class UserResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return parent::toArray($request);
    }
}

Sekarang ubah toArray() agar mengembalikan struktur yang sudah didefinisikan:

public function toArray(Request $request): array
{
    return [
        'id'         => $this->id,
        'name'       => $this->name,
        'email'      => $this->email,
        'avatar_url' => $this->avatar ? asset('storage/' . $this->avatar) : null,
        'role'       => $this->role,
        'joined_at'  => $this->created_at->toDateString(),
    ];
}

Hasilnya? Frontend developer tidak akan pernah lagi menerima field password, remember_token, atau field sensitif lain yang bocor secara tidak sengaja.

Menggunakan Resource di Controller

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Http\Resources\UserResource;
use App\Http\Resources\UserCollection;
use App\Models\User;

class UserController extends Controller
{
    public function index()
    {
        return new UserCollection(User::paginate(15));
    }

    public function show(User $user)
    {
        return new UserResource($user);
    }
}

Sekarang setiap response sudah melewati layer transformasi yang konsisten.

Standarisasi Wrapper dengan $wrap

Secara default, Laravel membungkus response dalam key data. Kamu bisa ubah atau seragamkan ini di semua resource:

class UserResource extends JsonResource
{
    public static $wrap = 'user'; // Ubah jadi 'user' bukan 'data'
}

Atau kalau ingin semua resource pakai wrapper yang sama, set di AppServiceProvider:

use Illuminate\Http\Resources\Json\JsonResource;

public function boot(): void
{
    JsonResource::withoutWrapping(); // Hapus wrapper 'data'
}

Pilih salah satu dan konsisten. Jangan campur aduk antara response yang pakai wrapper dan yang tidak.

Menangani Pagination, Relasi, dan Conditional Fields di Resource

Pagination yang Otomatis Rapi

Saat menggunakan ResourceCollection dengan paginate(), Laravel secara otomatis menambahkan metadata pagination:

{
    "data": [...],
    "links": {
        "first": "https://api.example.com/users?page=1",
        "last": "https://api.example.com/users?page=5",
        "prev": null,
        "next": "https://api.example.com/users?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 5,
        "per_page": 15,
        "to": 15,
        "total": 75
    }
}

Frontend developer langsung tahu berapa total data, halaman berapa sekarang, dan ada next page atau tidak. Tanpa perlu bertanya ke backend developer.

Menyertakan Relasi dengan Benar

Jangan load relasi di dalam toArray() tanpa kondisi. Ini akan menyebabkan N+1 query problem.

Cara yang benar adalah gunakan whenLoaded():

public function toArray(Request $request): array
{
    return [
        'id'       => $this->id,
        'name'     => $this->name,
        'email'    => $this->email,
        // Hanya sertakan posts jika sudah di-eager load
        'posts'    => PostResource::collection($this->whenLoaded('posts')),
        'profile'  => new ProfileResource($this->whenLoaded('profile')),
    ];
}

Kemudian di controller, load relasi sesuai kebutuhan:

// Tanpa relasi
return new UserResource(User::find($id));

// Dengan relasi
return new UserResource(User::with(['posts', 'profile'])->find($id));

Hasilnya? Response akan menyertakan posts dan profile hanya ketika data tersebut memang di-load. Tidak ada field null yang membingungkan.

Conditional Fields dengan when()

Kadang ada field yang hanya boleh muncul untuk kondisi tertentu, misalnya hanya untuk role admin:

public function toArray(Request $request): array
{
    return [
        'id'             => $this->id,
        'name'           => $this->name,
        'email'          => $this->email,
        // Field ini hanya muncul jika user yang request adalah admin
        'internal_notes' => $this->when(
            $request->user()?->isAdmin(),
            $this->internal_notes
        ),
        // Field ini hanya muncul jika model punya nilai
        'deleted_at'     => $this->when(
            $this->trashed(),
            $this->deleted_at
        ),
    ];
}

Dengan when(), kamu tidak perlu menulis logika kondisional di controller. Semuanya terpusat di resource class.

Menambahkan Metadata Tambahan

Gunakan additional() untuk menambahkan data di luar object utama:

return (new UserResource($user))
    ->additional([
        'meta' => [
            'version'      => 'v2',
            'generated_at' => now()->toIso8601String(),
        ]
    ]);

Standar Error Response dengan Exception Handler Terpusat di Laravel

Konsistensi bukan hanya untuk response sukses. Error response yang tidak konsisten sama berbahayanya.

Membuat Format Error yang Seragam

Buka file app/Exceptions/Handler.php dan override method register():

<?php

namespace App\Exceptions;

use Illuminate\Auth\AuthenticationException;
use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use Illuminate\Http\JsonResponse;
use Illuminate\Validation\ValidationException;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
use Throwable;

class Handler extends ExceptionHandler
{
    public function register(): void
    {
        $this->renderable(function (Throwable $e, $request) {
            if ($request->expectsJson()) {
                return $this->handleApiException($e, $request);
            }
        });
    }

    private function handleApiException(Throwable $e, $request): JsonResponse
    {
        // Validasi error
        if ($e instanceof ValidationException) {
            return response()->json([
                'status'  => 'error',
                'message' => 'Data yang dikirim tidak valid.',
                'errors'  => $e->errors(),
            ], 422);
        }

        // Authentication error
        if ($e instanceof AuthenticationException) {
            return response()->json([
                'status'  => 'error',
                'message' => 'Anda perlu login untuk mengakses resource ini.',
                'errors'  => null,
            ], 401);
        }

        // Not found error
        if ($e instanceof NotFoundHttpException) {
            return response()->json([
                'status'  => 'error',
                'message' => 'Resource yang Anda cari tidak ditemukan.',
                'errors'  => null,
            ], 404);
        }

        // Generic server error
        $statusCode = method_exists($e, 'getStatusCode')
            ? $e->getStatusCode()
            : 500;

        return response()->json([
            'status'  => 'error',
            'message' => app()->isProduction()
                ? 'Terjadi kesalahan pada server. Silakan coba lagi.'
                : $e->getMessage(),
            'errors'  => null,
        ], $statusCode);
    }
}

Sekarang semua error response akan punya struktur yang sama: status, message, dan errors.

Membuat ApiResponse Helper

Untuk response sukses, buat helper class agar format selalu konsisten:

<?php

namespace App\Http\Responses;

use Illuminate\Http\JsonResponse;

class ApiResponse
{
    public static function success(
        mixed $data = null,
        string $message = 'Berhasil.',
        int $code = 200
    ): JsonResponse {
        return response()->json([
            'status'  => 'success',
            'message' => $message,
            'data'    => $data,
        ], $code);
    }

    public static function created(
        mixed $data = null,
        string $message = 'Data berhasil dibuat.'
    ): JsonResponse {
        return self::success($data, $message, 201);
    }

    public static function noContent(
        string $message = 'Data berhasil dihapus.'
    ): JsonResponse {
        return response()->json([
            'status'  => 'success',
            'message' => $message,
            'data'    => null,
        ], 200);
    }
}

Penggunaannya di controller menjadi sangat bersih:

use App\Http\Responses\ApiResponse;

public function store(StoreUserRequest $request)
{
    $user = User::create($request->validated());

    return ApiResponse::created(
        new UserResource($user),
        'Akun berhasil dibuat.'
    );
}

public function destroy(User $user)
{
    $user->delete();

    return ApiResponse::noContent();
}

Setiap response yang keluar dari API kamu sekarang punya struktur yang 100% dapat diprediksi.

Kesulitan dengan tugas programming atau butuh bantuan coding? KerjaKode siap membantu menyelesaikan tugas IT dan teknik informatika Anda. Dapatkan bantuan profesional di jasa tugas IT KerjaKode.

Dokumentasi API Otomatis dengan Scribe agar Tim Tidak Perlu Tebak-Tebakan

Standarisasi response tidak ada artinya kalau tidak ada dokumentasi yang bisa dibaca tim.

Scribe adalah package dokumentasi API terbaik untuk Laravel saat ini. Dia bisa generate dokumentasi otomatis dari code, route, dan docblock yang ada.

Instalasi Scribe

composer require --dev knuckleswtf/scribe
php artisan vendor:publish --tag=scribe-config

Anotasi Minimal di Controller

Tambahkan docblock di controller untuk memperkaya dokumentasi:

/**
 * Ambil daftar semua pengguna.
 *
 * Endpoint ini mengembalikan daftar pengguna yang sudah terdaftar,
 * diurutkan berdasarkan tanggal bergabung terbaru.
 *
 * @group User Management
 * @queryParam page integer Nomor halaman. Default: 1. Example: 1
 * @queryParam per_page integer Jumlah data per halaman. Default: 15. Example: 15
 * @authenticated
 */
public function index()
{
    return new UserCollection(User::paginate(15));
}

Generate Dokumentasi

php artisan scribe:generate

Scribe akan otomatis membuat halaman dokumentasi HTML yang bisa diakses di /docs. Tim frontend dan mobile developer bisa langsung lihat semua endpoint, format request, dan contoh response tanpa harus tanya-tanya ke backend developer.

Tips Scribe dengan API Resources

Scribe bisa membaca toArray() dari API Resource dan otomatis menampilkan struktur response. Tambahkan type hints yang benar untuk hasil yang lebih akurat:

/**
 * @response {
 *   "status": "success",
 *   "message": "Berhasil.",
 *   "data": {
 *     "id": 1,
 *     "name": "Budi Santoso",
 *     "email": "[email protected]",
 *     "role": "admin",
 *     "joined_at": "2026-01-15"
 *   }
 * }
 */
public function show(User $user)
{
    return ApiResponse::success(new UserResource($user));
}

Checklist Standarisasi API Sebelum Go Live

Sebelum tim kamu mulai consume API ini, pastikan hal-hal berikut sudah ada:

• Resource class untuk setiap model yang di-expose ke API
• whenLoaded() dipakai di setiap relasi dalam resource
• Exception handler sudah override untuk JSON response
• ApiResponse helper dipakai konsisten di semua controller
• Scribe terkonfigurasi dan dokumentasi bisa diakses oleh tim
• Format tanggal seragam — pilih ISO 8601 (2026-07-24T10:30:00Z) dan konsisten
• Field naming convention seragam — pilih snake_case atau camelCase, jangan campur

Hasil Nyata yang Bisa Dirasakan Tim

Dengan implementasi yang sudah dijelaskan di atas, manfaatnya langsung terasa:

Frontend developer bisa percaya bahwa data.id selalu ada dan selalu integer. Mobile developer tidak perlu nulis defensive code untuk setiap kemungkinan format response. QA engineer bisa tulis test case yang spesifik karena response sudah predictable.

Dan yang paling penting: onboarding developer baru jadi jauh lebih cepat karena dokumentasi otomatis dari Scribe selalu up to date dengan kode yang ada.

Konsistensi API bukan kemewahan. Ini adalah fondasi dari kolaborasi tim yang sehat.

Semakin cepat standar ini diterapkan, semakin sedikit waktu yang terbuang untuk hal-hal yang seharusnya tidak perlu didebat setiap sprint.