Konsep REST API

Aplikasi Laravel kita jarang berdiri sendiri. Frontend JavaScript, aplikasi mobile, dan layanan pihak ketiga membutuhkan cara berkomunikasi dengan aplikasi kita — dan cara paling umum hari ini adalah REST API. REST (Representational State Transfer) adalah gaya arsitektur yang memanfaatkan infrastruktur HTTP yang sudah ada: URL menamai data, method menentukan aksi, dan status code melaporkan hasil. Chapter ini membangun fondasi konseptual yang akan kita pakai di sepanjang Section API Development, jadi mari kita mulai dari prinsipnya sebelum menyentuh satu baris kode Laravel pun.

Resource Adalah Kata Benda, Bukan Kata Kerja #

Prinsip pertama REST: setiap endpoint menunjuk resource — entitas data seperti post, user, atau komentar. URL seharusnya menamai resource dengan kata benda, sedangkan aksi ditentukan oleh HTTP method. Gaya lama seperti /getPosts mencampurkan aksi ke dalam nama URL dan mengabaikan method GET yang sudah jelas berarti “ambil data”. REST memisahkan keduanya dengan tegas:

Perhatikan polanya: identitas resource konsisten berada di /posts dan /posts/{id}, sementara method GET, POST, PUT, dan DELETE memberikan makna pada URL yang sama. Satu resource, banyak aksi.

HTTP Method dan Pemetaan CRUD #

HTTP method bukan sekadar dekorasi — setiap method membawa janji perilaku. Tabel berikut merangkum pemetaan method ke operasi CRUD beserta sifat pentingnya:

Idempotent berarti request yang dikirim berulang menghasilkan keadaan akhir yang sama. Sifat ini penting ketika jaringan tidak stabil dan client otomatis mengulang request — PUT /posts/1 yang terkirim dua kali tetap menghasilkan satu post dengan isi yang sama, sedangkan POST /posts yang terkirim dua kali bisa membuat dua post.

Status Code sebagai Bahasa Hasil #

Response API tidak cukup hanya membawa data — baris pertamanya harus jujur melaporkan hasil operasi. HTTP membagi status code menjadi lima keluarga:

Kode yang paling sering kita pakai sehari-hari: 200 untuk GET yang sukses, 201 setelah resource berhasil dibuat, 204 untuk DELETE yang sukses tanpa body, 404 saat resource tidak ada, 405 saat method tidak didukung endpoint, dan 422 saat validasi gagal. Client yang membaca status code dengan benar tidak perlu menebak-menebak isi body.

Stateless: Setiap Request Berdiri Sendiri #

REST mensyaratkan server stateless — server tidak menyimpan ingatan percakapan antar request. Setiap request harus membawa sendiri seluruh informasi yang dibutuhkan: identitas pemanggil (misalnya token di header Authorization), parameter, dan data yang dikirim. Kontrasnya dengan aplikasi web tradisional yang mengandalkan session di server untuk mengenali pengguna antar halaman. Akibat statelessness, setiap request bisa dilayani oleh server mana pun dalam kluster — kondisi yang memudahkan penskalaan horizontal.

API Routes vs Web Routes di Laravel #

Laravel menyediakan dua dunia route yang terpisah karena perbedaan mendasar ini:

Route API secara otomatis mendapat prefix /api — kita bedah mekanismenya di chapter API Routing . Karena tidak ada session, tidak ada pula proteksi CSRF dan tidak ada cookie login; identitas dikirim ulang di setiap request lewat header.

REST dalam Praktik #

Teori di atas akan lebih melekat jika kita lihat sendiri bagaimana server merespons. Kita definisikan endpoint sederhana untuk resource posts:

php
<?php

// routes/api.php

use App\Models\Post;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::get('/ping', fn (): array => ['message' => 'pong']);

Route::get('/posts', fn () => Post::all(['id', 'title']));

Route::post('/posts', function (Request $request) {
    $post = Post::create($request->validate([
        'title' => 'required|string|max:100',
        'content' => 'required|string',
        'user_id' => 'required|integer|exists:users,id',
    ]));

    return response()->json($post, 201);
});

Route::get('/posts/{post}', fn (Post $post) => $post);

Route::delete('/posts/{post}', function (Post $post) {
    $post->delete();

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

Lalu kita tembak delapan request dari runner CLI dan mencatat status serta body-nya:

php
<?php

// uji-rest.php — jalankan: php uji-rest.php <path-proyek-laravel>
use Illuminate\Contracts\Http\Kernel;
use Illuminate\Http\Request;

$dir = $argv[1];
require $dir.'/vendor/autoload.php';
$app = require $dir.'/bootstrap/app.php';
$kernel = $app->make(Kernel::class);
$app->make(Illuminate\Contracts\Console\Kernel::class)->bootstrap();

$kirim = function (string $method, string $uri, ?array $json = null) use ($kernel) {
    $server = ['HTTP_ACCEPT' => 'application/json', 'CONTENT_TYPE' => 'application/json'];
    $request = Request::create('http://localhost'.$uri, $method, [], [], [], $server,
        $json ? json_encode($json) : null);
    $response = $kernel->handle($request);

    return sprintf('%-6s %-16s → HTTP %d  %s', $method, $uri,
        $response->getStatusCode(), $response->getContent());
};

echo $kirim('GET', '/api/ping'), PHP_EOL;
echo $kirim('GET', '/api/posts'), PHP_EOL;
echo $kirim('GET', '/api/posts/1'), PHP_EOL;
echo $kirim('POST', '/api/posts', ['title' => 'Post Baru', 'content' => 'Isi baru.', 'user_id' => 1]), PHP_EOL;
echo $kirim('DELETE', '/api/posts/1'), PHP_EOL;
echo $kirim('GET', '/api/posts/1'), PHP_EOL;
echo $kirim('PUT', '/api/posts'), PHP_EOL;
echo $kirim('GET', '/api/getPosts'), PHP_EOL;

Output yang Dihasilkan:

text
GET    /api/ping        → HTTP 200  {"message":"pong"}
GET    /api/posts       → HTTP 200  [{"id":1,"title":"Belajar REST API"}]
GET    /api/posts/1     → HTTP 200  {"id":1,"user_id":1,"title":"Belajar REST API","content":"Konten post pertama.","created_at":"2026-01-02T09:00:00.000000Z","updated_at":"2026-01-02T09:00:00.000000Z"}
POST   /api/posts       → HTTP 201  {"title":"Post Baru","content":"Isi baru.","user_id":1,"updated_at":"2026-01-02T09:00:00.000000Z","created_at":"2026-01-02T09:00:00.000000Z","id":2}
DELETE /api/posts/1     → HTTP 204
GET    /api/posts/1     → HTTP 404  {
    "message": "No query results for model [App\\Models\\Post] 1"
}
PUT    /api/posts       → HTTP 405  {
    "message": "The PUT method is not supported for route api/posts. Supported methods: GET, HEAD, POST."
}
GET    /api/getPosts    → HTTP 404  {
    "message": "The route api/getPosts could not be found."
}

Mari kita baca hasilnya baris demi baris:

GET /api/posts → 200: method dan resource cocok, daftar post dikembalikan sebagai array JSON.
POST /api/posts → 201: resource baru lahir dengan ID 2, tepat seperti janji status Created.
DELETE /api/posts/1 → 204: penghapusan sukses dan body sengaja kosong — tidak ada lagi yang perlu dilaporkan.
GET /api/posts/1 setelah dihapus → 404: resource sudah tidak ada, server jujur mengatakannya.
PUT /api/posts → 405: endpoint collection hanya menerima GET dan POST, jadi Laravel menolak method PUT dan menyebutkan method yang didukung.
GET /api/getPosts → 404: URL gaya lama memang tidak pernah kita definisikan — noun-only menang.

Prinsip REST — resource berbenda, method bermakna, status code jujur, dan request stateless — kini menjadi kompas kita. Langkah berikutnya adalah mengimplementasikannya di Laravel secara sistematis, dimulai dari cara framework mendaftarkan route API di API Routing .