Lesson 0020 · System Design · Modul Reliabilitas & API · ±20 menit

Gaya API: REST, gRPC, WebSocket, long polling, SSE

Lima cara client dan server bicara, satu pertanyaan untuk memilihnya ("siapa yang perlu bicara duluan?"), dan pagination yang tidak melambat di halaman 10.000

Sebelumnya, di review 0019, Anda menguji modul Data dan Caching. Langkah 3 kerangka interview (lesson 0027) meminta "API + data model". Lesson ini membahas bagian API-nya: gaya mana yang dipilih, dan bagaimana mengembalikan daftar panjang.

Target lesson ini: Anda bisa menjawab "API apa yang Anda pakai untuk fitur ini?" dalam 60 detik: memilih REST, gRPC, SSE, WebSocket, atau long polling dari arah komunikasi dan angka latency, lalu menjelaskan kenapa cursor lebih baik dari offset untuk daftar panjang.

1. REST: default untuk request-response

REST memodelkan API sebagai resource (/orders/42) yang dimanipulasi dengan method HTTP: GET membaca, POST membuat, PUT mengganti, DELETE menghapus. Method punya makna yang dijanjikan RFC 9110. Contoh terpenting untuk modul ini: method disebut idempotent kalau efek beberapa request identik sama dengan efek satu request, dan PUT, DELETE, serta method aman seperti GET termasuk di dalamnya. ^[1] Itulah yang membuat retry aman (lesson 0022). POST tidak idempotent, jadi butuh idempotency key (lesson 0017).

Kenapa REST jadi default: semua client bisa memanggilnya (browser, mobile, curl), response GET bisa di-cache oleh CDN, dan setiap engineer sudah paham polanya. Di interview, mulai dari REST dan pindah hanya kalau ada alasan.

2. gRPC: kontrak ketat antar service

gRPC adalah framework RPC (remote procedure call: memanggil fungsi di mesin lain seolah fungsi lokal). Kontraknya ditulis dengan Protocol Buffers, yang dipakai sekaligus sebagai IDL (bahasa definisi interface) dan format pesan biner. ^[2] Selain panggilan biasa (unary), gRPC punya server streaming, client streaming, dan bidirectional streaming. ^[3] Menurut FAQ resminya, gRPC mengikuti semantik HTTP di atas HTTP/2 dan mengizinkan streaming full-duplex. Untuk browser dibutuhkan proyek terpisah, gRPC-Web. ^[4]

Jadi tempat alaminya adalah komunikasi service-to-service internal: kode client di-generate dari kontrak, pesan biner lebih kecil, dan streaming tersedia. Untuk API publik yang dipanggil browser, REST biasanya tetap lebih murah.

3. Server perlu bicara duluan: long polling, SSE, WebSocket

HTTP biasa hanya menjawab saat ditanya. Kalau server punya data baru (pesan chat, harga, status), ada tiga cara mendorongnya ke client:

Long polling. Client mengirim request, server menahannya sampai ada data (atau timeout), menjawab, lalu client langsung bertanya lagi. RFC 6202 menyebutnya salah satu dari dua mekanisme paling umum untuk komunikasi "server-initiated" di atas HTTP. ^[5] Bekerja di mana saja, tapi setiap pesan membayar satu request baru.
SSE (Server-Sent Events). Satu response HTTP yang tidak pernah selesai, bertipe text/event-stream, berisi aliran event. API EventSource di browser menyambung ulang sendiri setelah "reconnection time" dan mengirim header Last-Event-ID supaya server bisa melanjutkan. ^[6] Satu arah saja: server → client.
WebSocket. Koneksi dua arah di atas TCP yang dibuka lewat handshake HTTP. RFC 6455 menyebut tujuannya: komunikasi dua arah untuk aplikasi browser tanpa membuka banyak koneksi HTTP seperti long polling. ^[7] Cocok untuk chat dan game; biayanya, koneksi menjadi stateful.

Pertanyaan pertama adalah arah komunikasi, bukan teknologi. Long polling adalah cadangan kalau SSE atau WebSocket tidak bisa dipakai (proxy lama, client terbatas).

Latihan 1 — Memilih gaya API

Jawab tanpa scroll ke atas. Soal yang sama akan muncul lagi, diacak, di review 0026.

Kuis di lesson ini adalah feedback cepat, bukan bukti penguasaan; yang dicatat hanya hasil review 0026.

4. Pagination: offset vs cursor

Endpoint daftar (GET /orders) tidak boleh mengembalikan sejuta baris. Dua cara memotongnya:

	Offset: `?offset=40&limit=20`	Cursor: `?after=eyJpZCI6OTgxfQ`
Query	`ORDER BY id DESC LIMIT 20 OFFSET 40`	`WHERE id < 981 ORDER BY id DESC LIMIT 20`
Halaman dalam	Makin lambat: baris yang dilewati `OFFSET` tetap dihitung server, jadi offset besar tidak efisien ^[8]	Konstan: index langsung melompat ke `id < 981`
Data baru masuk	Halaman bergeser, user melihat item ganda	Stabil, melanjutkan dari item terakhir
Lompat ke halaman N	Bisa	Tidak bisa, hanya "berikutnya"

Cursor biasanya dikirim sebagai token opaque (misalnya id terakhir yang di-encode base64) supaya server bebas mengubah isinya nanti. Untuk feed dan infinite scroll, pilih cursor. Untuk tabel admin kecil yang butuh "halaman 7 dari 12", offset cukup.

Latihan 2 — Pagination

5. Kapan tidak perlu

Sinyal yang membenarkan WebSocket atau streaming: data harus sampai dalam hitungan detik atau kurang, dan polling mulai mendominasi beban. Hitung dulu: 1.000 user yang polling tiap 30 detik hanya ±33 request per detik, ringan untuk satu server. Notifikasi yang boleh terlambat 30 detik tidak butuh koneksi persistent.

Biaya dan risiko: WebSocket membuat server stateful. Setiap instance memegang ribuan koneksi terbuka, load balancer harus mendukung koneksi panjang, deploy memutus koneksi sehingga client butuh logika reconnect, dan pesan ke user di instance lain butuh pub/sub (lesson 0016). gRPC menambah langkah generate kode, butuh gRPC-Web atau gateway untuk browser, dan lebih sulit di-debug karena pesannya biner.

Alternatif lebih murah: REST + short polling sebagai v1; SSE kalau aliran hanya satu arah (masih HTTP biasa, reconnect gratis dari browser); offset pagination untuk tabel kecil. Naik ke WebSocket hanya kalau requirement latency atau arah komunikasi menuntutnya.

Latihan lisan — Ucapkan dengan suara keras

Pasang timer dan jawab dengan suara keras, seolah sedang interview. Jangan buka jawaban contoh sebelum selesai. Soal ini juga ada di bank soal dan bisa ditarik review 0026.

"Kita membangun fitur chat dan halaman daftar order untuk aplikasi web. Gaya API apa yang Anda pakai untuk masing-masing, dan kenapa?" (60 detik)

Bandingkan dengan jawaban contoh dan checklist-nya

"Untuk daftar order saya pakai REST: request-response biasa, method HTTP yang jelas, GET bisa di-cache, dan pagination pakai cursor supaya halaman tidak bergeser dan query tetap memakai index. Chat butuh dua arah dengan latency rendah, jadi WebSocket: satu koneksi untuk kirim dan terima. Kalau hanya perlu push satu arah, misalnya status pengiriman, SSE lebih sederhana karena HTTP biasa dan browser reconnect sendiri. gRPC saya simpan untuk komunikasi antar service internal, karena browser butuh gRPC-Web. Biayanya: WebSocket itu koneksi stateful, jadi load balancer dan deploy harus menangani koneksi panjang. Kalau user masih sedikit dan latency beberapa detik dapat diterima, polling REST cukup sebagai v1."

Checklist: apakah Anda menyebut…

REST untuk request-response biasa seperti daftar order?
WebSocket untuk komunikasi dua arah latency rendah seperti chat?
SSE sebagai alternatif lebih sederhana untuk push satu arah?
gRPC cocok untuk service internal, browser butuh gRPC-Web?
pagination cursor (bukan offset besar) untuk daftar yang panjang?
biaya koneksi stateful dan polling sebagai v1 kalau angka mengizinkan?

Lulus jika minimal 4 dari 6.

Bacaan lanjutan (opsional, tidak dihitung dalam durasi) gRPC: Core concepts, architecture and lifecycle, terutama bagian empat jenis RPC dan deadline, ±15 menit.

Berikutnya, lesson 0021: API sudah dipilih. Bagaimana mencegah satu client menghabiskan kapasitasnya?

Istilah: GLOSSARY.md (bagian "Reliabilitas & API") · Indeks: semua lesson System Design

Ada yang belum jelas? Tanyakan ke saya (agent) di terminal, misalnya: "Kenapa SSE tidak bisa dipakai untuk chat?", "Bagaimana cursor di-encode supaya client tidak bisa mengubahnya?"

Sumber: [1] RFC 9110 HTTP Semantics, §9.2.2 Idempotent Methods · [2] gRPC: Introduction to gRPC · [3] gRPC: Core concepts, architecture and lifecycle · [4] gRPC: FAQ · [5] RFC 6202 Long Polling and Streaming in Bidirectional HTTP, §2 · [6] WHATWG HTML Standard, §9.2 Server-sent events · [7] RFC 6455 The WebSocket Protocol, §1.1 · [8] PostgreSQL docs: LIMIT and OFFSET