Hampir setiap aplikasi di ponsel Anda berbicara dengan server lewat API, dan sebagian besar API itu menyebut dirinya REST API. REST API bukan produk, library, atau protokol yang Anda install. Ia adalah gaya arsitektur: seperangkat batasan tentang cara client dan server berbicara lewat HTTP, yang didefinisikan Roy Fielding dalam disertasi doktoralnya tahun 2000 di University of California, Irvine. Memahami batasan itu menjelaskan mengapa endpoint terlihat seperti sekarang, mengapa lima method HTTP yang sama muncul di mana-mana, dan mengapa angka tiga digit bisa memberi tahu Anda persis apa yang salah.
Poin Utama
REST adalah singkatan dari Representational State Transfer, gaya arsitektur yang didefinisikan Roy Fielding pada tahun 2000, bukan standar atau protokol.
Resource adalah kata benda dengan URL stabil, seperti `/users/42`. Method HTTP adalah kata kerjanya: GET membaca, POST membuat, PUT mengganti, PATCH memperbarui sebagian resource, DELETE menghapusnya.
Request harus stateless: ia membawa semua yang dibutuhkan server, sehingga server mana pun bisa menjawabnya tanpa mengingat request sebelumnya.
Status code dikelompokkan berdasarkan kelas: 2xx berarti sukses, 3xx pengalihan, 4xx kesalahan client, 5xx kesalahan server.
Sebagian besar API yang menyebut dirinya REST sebenarnya adalah HTTP API berorientasi resource. Itu tidak masalah, dan tetap menjadi cara paling dipahami untuk membangun API publik.
Apa Sebenarnya REST Itu
Fielding memperkenalkan REST untuk menjelaskan arsitektur yang sudah membuat web bisa diskalakan. Dalam disertasinya, REST adalah seperangkat enam batasan, dan API yang mengikutinya disebut RESTful. Batasan-batasan itu, seperti dirangkum Wikipedia dan panduan desain API backend Art of Code, adalah:
Client-server. Antarmuka pengguna dan penyimpanan data adalah urusan yang terpisah, sehingga masing-masing bisa berkembang sendiri.
Stateless. Setiap request membawa semua yang dibutuhkan server untuk memahaminya. Server tidak menyimpan sesi client di antara request.
Cacheable. Response harus menyatakan apakah ia bisa di-cache, sehingga client dan perantara bisa menggunakannya kembali.
Uniform interface. Setiap resource ditangani dengan cara yang sama, lewat seperangkat operasi yang konsisten.
Layered system. Client tidak bisa membedakan apakah ia berbicara dengan server asal, proxy, atau cache di antaranya.
Code on demand (opsional). Server boleh mengirim kode yang bisa dieksekusi, seperti script, untuk dijalankan client.
Uniform interface sendiri punya empat bagian: resource diidentifikasi lewat URL, resource diubah lewat representasi (biasanya JSON saat ini), pesan bersifat self descriptive (method, header, dan media type menjelaskan cara membacanya), dan hypermedia menggerakkan state aplikasi, artinya response berisi link ke hal yang bisa Anda lakukan selanjutnya. Bagian terakhir itu, yang sering disebut HATEOAS, hampir tidak pernah diimplementasikan dalam praktik. Fielding sendiri mencatat rasa frustrasinya karena orang menyebut interface HTTP apa pun sebagai REST API. Label yang jujur untuk sebagian besar API di dunia nyata adalah HTTP API berorientasi resource, dan artikel ini memakai kata REST dalam pengertian sehari-hari itu.
Resource Adalah Kata Benda, Method Adalah Kata Kerja
Aturan desain intinya sederhana: modelkan sesuatu sebagai resource, beri masing-masing URL yang stabil, dan gunakan method HTTP untuk bertindak atasnya. Pengguna adalah resource. Daftar pengguna adalah resource koleksi. Satu pesanan adalah resource. URL adalah kata benda, method adalah kata kerja.
GET /users mengembalikan daftar pengguna. GET /users/42 mengembalikan pengguna 42.
POST /users membuat pengguna baru dalam koleksi, dengan data di body request.
PUT /users/42 mengganti pengguna 42 sepenuhnya dengan body yang Anda kirim.
PATCH /users/42 hanya mengubah field yang Anda kirim, sisanya tidak berubah.
DELETE /users/42 menghapus pengguna 42.
Dua sifat method lebih penting daripada namanya. Method disebut safe bila tidak pernah mengubah state, jadi GET, HEAD, dan OPTIONS adalah safe. Method disebut idempotent bila mengirimnya sekali atau berkali-kali menghasilkan efek yang sama, jadi PUT dan DELETE bersifat idempotent sementara POST tidak. Panduan Art of Code mencatat bahwa RFC 9110 mendefinisikan istilah-istilah ini, dan client, proxy, serta logika retry mengandalkannya. Itulah mengapa request yang gagal bisa dicoba ulang dengan aman untuk PUT tapi tidak boleh dicoba ulang begitu saja untuk POST: mencoba ulang POST pembayaran tanpa idempotency key bisa menagih dua kali, sementara mencoba ulang PUT hanya menulis ulang data yang sama.
Desain endpoint yang baik mengikuti hal ini. Gunakan kata benda jamak untuk koleksi (`/users`, `/orders`), bersarang maksimal satu level (`/users/42/orders`), filter dengan query parameter (`/orders?status=shipped`), dan jangan pernah menaruh kata kerja di URL. `GET /users/42/cancel` merusak model: crawler atau pratinjau link bisa memanggilnya, dan ia akan mengubah state lewat method yang safe. Bentuk RESTful-nya adalah `POST /users/42/cancellation` atau pembaruan status dengan PATCH, di mana aksinya eksplisit dan methodnya bukan method safe.
Sebuah Request, Langkah demi Langkah
Request REST adalah HTTP biasa, dan melihat bagian-bagiannya menghilangkan misteri. Ambil contoh request untuk membaca profil pengguna:
Method dan URL: `GET https://api.example.com/users/42`
Header: `Accept: application/json` menyatakan format yang diinginkan client, dan `Authorization: Bearer <token>` membuktikan siapa pemanggilnya.
Body: Request GET biasanya tidak punya body. POST dan PUT membawa body, biasanya JSON.
Server menjawab dengan tiga bagiannya sendiri:
Status code: angka tiga digit, seperti 200 untuk sukses atau 404 untuk resource yang hilang.
Header: `Content-Type: application/json` menyatakan apa isi body, dan header cache menyatakan apakah body bisa disimpan.
Body: representasi dari resource, biasanya JSON, seperti `{"id": 42, "name": "Zahra", "email": "zahra@example.com"}`.
Karena request bersifat stateless, server membutuhkan token di setiap panggilan. Itu terdengar boros, tapi justru itulah yang membuat API bisa diskalakan: server mana pun di balik load balancer bisa menjawab request apa pun, tidak ada server yang harus mengingat sesi Anda, dan server yang gagal bisa diganti tanpa kehilangan state siapa pun. Bayarannya adalah client harus mengirim ulang kredensial dan konteksnya setiap kali, itulah mengapa token, bukan sesi di sisi server, menjadi standar untuk API publik.
Status Code: Jawaban Singkat Server
Status code dikelompokkan ke dalam lima kelas, dan mempelajari kelasnya lebih berguna daripada menghafal setiap kode. Kode-kode umum, seperti tercantum dalam referensi standar, adalah:
2xx, sukses: 200 OK (request berhasil), 201 Created (POST membuat resource baru), 204 No Content (sukses, tidak ada yang dikembalikan, umum untuk DELETE).
3xx, pengalihan: 301 Moved Permanently, 302 Found (pengalihan sementara), 304 Not Modified (salinan cache Anda masih bagus).
4xx, kesalahan client: 400 Bad Request (input cacat atau tidak valid), 401 Unauthorized (autentikasi hilang atau gagal), 403 Forbidden (sudah terautentikasi tapi tidak diizinkan), 404 Not Found (tidak ada resource seperti itu), 409 Conflict (duplikat atau bentrok versi), 429 Too Many Requests (dibatasi laju request).
5xx, kesalahan server: 500 Internal Server Error (kegagalan tak terduga), 502 Bad Gateway (layanan upstream mengembalikan response yang buruk), 503 Service Unavailable (kelebihan beban atau sedang perawatan).
Kelasnya memberi tahu siapa yang harus bertindak. Kesalahan 4xx berarti perbaiki request: periksa URL, token, atau body. Kesalahan 5xx berarti masalahnya ada di sisi server, dan mencoba lagi nanti mungkin berhasil. API yang baik juga mengembalikan body error yang berguna bersama kode 4xx, bukan hanya angkanya: field mana yang gagal, mengapa gagal, dan seperti apa nilai yang benar. Kode 400 tanpa penjelasan memaksa setiap developer menebak-nebak, dan tebakan adalah cara bug dikirim ke produksi.
Autentikasi, Versioning, dan Pagination
Tiga pertanyaan praktis muncul di hampir setiap API nyata, dan REST memberi jawaban konvensional, bukan aturan kaku.
Autentikasi biasanya berarti token yang dikirim di header `Authorization`. Pola umumnya adalah API key untuk panggilan server ke server dan bearer token OAuth 2.0 untuk aplikasi yang menghadap pengguna, di mana access token berumur pendek diperbarui dengan refresh token berumur lebih panjang. Server memeriksa token di setiap request, sehingga batasan stateless tetap terjaga.
Pagination menjawab masalah sederhana: koleksi dengan sejuta item tidak bisa dikembalikan dalam satu response. API biasanya mengembalikan satu halaman dalam satu waktu, dengan query parameter seperti `?page=2&limit=50` atau parameter cursor seperti `?after=<id>`, ditambah metadata untuk jumlah total atau link ke halaman berikutnya. Pagination cursor lebih disukai untuk daftar besar atau yang berubah, karena nomor halaman bergeser saat item ditambah atau dihapus.
Versioning menjawab masalah yang lebih sulit: bagaimana mengubah API tanpa merusak setiap client. Pendekatan umumnya adalah versi di URL (`/v1/users`, `/v2/users`) atau versi di header. Versioning lewat URL adalah yang paling terlihat dan paling mudah di-debug, dan itulah yang dipilih sebagian besar API publik. Apa pun skemanya, aturannya sama: jangan pernah diam-diam mengubah arti sebuah field. Tambahkan field baru dengan bebas, deprecated field lama dengan pemberitahuan, dan hanya hapus field itu di versi major yang baru.
Di Mana REST Cocok, dan Di Mana Tidak
REST menjadi default untuk API publik karena alasan yang bagus: ia memakai mesin web itu sendiri, mudah di-cache, mudah di-debug dengan tool HTTP biasa, dan hampir setiap bahasa punya client untuknya. Ia juga punya batas yang jujur. Client yang membutuhkan tepat lima field dari tiga resource harus membuat beberapa request atau menerima overfetching, masalah yang dirancang untuk diselesaikan GraphQL. Client yang membutuhkan update live harus polling atau menambah channel terpisah seperti WebSockets atau server sent events, karena request HTTP dimulai oleh client. Dan HATEOAS yang ketat, di mana client menemukan setiap aksi dari link di response, jarang sepadan dengan kompleksitasnya saat client dan server dibangun oleh tim yang sama.
Itulah mengapa lanskap saat ini bercampur, bukan dogmatis. API data publik tetap RESTful karena sederhana dan bisa di-cache. Layanan internal kadang memakai gRPC demi kecepatan. Front end produk kadang memakai GraphQL untuk membentuk response secara presisi. Mengetahui REST tetap berguna dalam semua kasus itu, karena konsepnya, resource, method, status code, statelessness, dan caching, muncul di mana-mana, bahkan saat protokolnya berubah. Jika Anda ingin sisi container dari cerita yang sama, penjelasan sebelumnya Docker Dijelaskan: Apa Itu Container dan Mengapa Developer Menyukainya membahas bagaimana server API itu benar-benar berjalan di produksi.
Pertanyaan yang Sering Diajukan
Apakah REST API sama dengan HTTP API?
Tidak persis. Setiap REST API memakai HTTP, tapi tidak setiap HTTP API bersifat RESTful. REST menambah batasan: resource dengan URL stabil, uniform interface, request stateless, dan response yang bisa di-cache. Sebagian besar API berlabel REST adalah HTTP API berorientasi resource yang mengikuti sebagian besar batasan itu tapi melewatkan hypermedia.
Mengapa JSON dan bukan XML?
JSON menang karena memetakan langsung ke struktur data bahasa modern, ringkas, dan mudah dibaca. XML masih dipakai di beberapa sistem enterprise dan legacy, tapi API publik baru hampir selalu memilih JSON.
Apa bedanya PUT dan PATCH?
PUT mengganti seluruh resource dengan body yang Anda kirim, jadi field yang hilang dianggap dihapus. PATCH hanya mengubah field yang Anda kirim. Gunakan PUT saat client punya state baru yang lengkap, dan PATCH saat ia hanya ingin mengubah satu atau dua field.
Apa yang sebaiknya dikembalikan POST?
Pembuatan yang sukses sebaiknya mengembalikan 201 Created, idealnya dengan header `Location` yang menunjuk ke URL resource baru dan resource yang dibuat di body. Mengembalikan 200 dengan resource juga umum, tapi 201 lebih presisi.
Bagaimana cara menangani error di client?
Periksa kelas status dulu. Pada 4xx, tampilkan atau catat body error dan perbaiki request; jangan mencoba ulang secara membabi buta. Pada 5xx atau kegagalan jaringan, coba ulang dengan jeda, tapi hanya untuk method safe atau idempotent kecuali API menyediakan idempotency key.
Apakah saya perlu belajar REST untuk memakai API?
Anda perlu kosakatanya: resource, method, status code, header, dan token. Dengan lima ide itu, Anda bisa membaca hampir semua dokumentasi API dan membuat panggilan sukses pertama dalam hitungan menit.
Kesimpulan
REST bertahan lebih dari dua dekade karena ia lebih merupakan disiplin daripada teknologi: beri nama sesuatu sebagai resource, gunakan kata kerja yang sudah disediakan HTTP, jawab dengan status code yang jujur, dan jaga setiap request tetap mandiri. Pelajari kebiasaan itu dan dokumentasi API berhenti terlihat seperti dinding endpoint dan mulai terlihat seperti peta. Lain kali Anda melihat `GET /users/42` mengembalikan 404, Anda akan tahu tiga hal sekaligus: apa yang diminta, apa yang salah, dan siapa yang harus memperbaikinya.
Baca artikel ini dalam bahasa Inggris: REST API Explained: How the Web's Most Common API Style Actually Works.