Hampir semua pekerjaan saya, mulai dari aplikasi full-stack, pipeline CI/CD, sampai integrasi AI, bertemu pada satu titik: API. Frontend berkomunikasi dengan backend melalui API, service berkomunikasi dengan service lain melalui API, dan model AI pun diakses melalui API.
Roadmap dari ByteByteGo ini sebelumnya saya simpan di catatan. Dalam tulisan ini saya menelaahnya satu per satu, sekaligus meluruskan beberapa label yang disederhanakan pada gambarnya.
Ada tiga hal yang perlu diluruskan lebih dulu:
- Kelompok “API styles” berisi hal yang berbeda jenis. REST adalah gaya arsitektur, SOAP dan WebSocket adalah protokol, GraphQL adalah spesifikasi query, dan gRPC adalah framework RPC. Semuanya dikelompokkan bersama karena sama-sama menentukan bentuk komunikasi client–server.
- Node.js bukan framework. Node.js adalah runtime JavaScript. Framework API di atasnya antara lain Express, Fastify, dan NestJS.
- Pagination muncul dua kali. Hal ini wajar, karena pagination merupakan bagian dari kontrak API sekaligus teknik menjaga performa.
Peta singkat
Topik | Yang dipelajari |
Pengenalan API | Definisi API, kontrak, serta jenis public, private, dan partner. |
Terminologi | Versi HTTP, method, status code, header, cookie, dan caching. |
Gaya API | REST, SOAP, GraphQL, gRPC, dan WebSocket. |
Autentikasi | Basic Auth, token, JWT, OAuth, dan session. |
Dokumentasi | OpenAPI, Swagger, Postman, Redoc, dan DapperDox. |
Fitur | Pagination, parameter, idempotency, versioning, HATEOAS, dan content negotiation. |
Performa | Caching, rate limiting, load balancing, indexing, scaling, dan performance testing. |
Gateway | Amazon API Gateway, Azure API Management, Kong, dan Nginx. |
Framework | Express/Node.js, Spring, Flask, Django, dan FastAPI. |
Pola integrasi | Gateway, event-driven, webhook, polling, dan batch processing. |
1. Pengenalan API
API adalah kontrak yang menentukan cara sebuah program meminta data atau menjalankan operasi pada program lain. Kontrak ini mencakup endpoint, format request dan response, aturan autentikasi, serta perilaku ketika terjadi error.
Berdasarkan pihak yang boleh menggunakannya, API dibagi menjadi tiga jenis:
- Public API terbuka untuk developer luas, umumnya tetap dengan API key dan batas pemakaian.
- Private API digunakan di dalam organisasi, misalnya antara frontend dan backend sendiri atau antar-service internal.
- Partner API dibuka khusus untuk mitra berdasarkan kesepakatan.
Satu prinsip yang saya pegang: “private” menyangkut siapa yang boleh mengakses, bukan jaminan keamanan. Jaringan internal bukan alasan untuk melewatkan autentikasi dan validasi input. Celah keamanan justru sering muncul pada sambungan antarbagian yang dianggap aman karena bersifat internal.
2. Terminologi API
Sebagian besar API web berjalan di atas HTTP, sehingga fondasinya ada di sini:
- Method seperti
GET,POST,PUT,PATCH, danDELETEmenyatakan maksud request.
- Status code menyatakan hasilnya, misalnya
200 OK,201 Created,400 Bad Request,401 Unauthorized,404 Not Found, dan429 Too Many Requests.
- Header membawa metadata seperti
Content-Type,Authorization, danCache-Control.
- Versi HTTP: HTTP/1.1, HTTP/2, dan HTTP/3 memiliki semantik yang sama. Perbedaannya terletak pada cara pesan dikirim melalui jaringan.
- Cookie adalah data kecil yang disimpan browser dan dikirim kembali ke server, sering digunakan untuk session. Atribut
HttpOnly,Secure, danSameSiteperlu diperhatikan.
- Caching menyimpan response agar request berikutnya tidak selalu sampai ke server. Perilakunya diatur melalui header seperti
Cache-Control,ETag, danLast-Modified.
Pemahaman pada bagian ini mempermudah debugging. Banyak masalah yang tampak seperti error API ternyata disebabkan oleh header yang keliru atau status code yang salah dibaca.
3. Gaya API
Tidak ada gaya API yang selalu paling baik. Pilihannya bergantung pada jenis client, bentuk data, dan kebutuhan operasional.
- REST memodelkan data sebagai resource yang diakses melalui URL dan method HTTP, misalnya
GET /orders/42. Gaya ini paling umum untuk API web karena sederhana dan memanfaatkan fitur HTTP seperti caching.
- SOAP adalah protokol berbasis XML dengan kontrak formal melalui WSDL. SOAP masih banyak ditemui pada integrasi enterprise, perbankan, dan sistem lama.
- GraphQL memungkinkan client meminta field yang dibutuhkan saja dalam satu query. Pendekatan ini mengurangi over-fetching, tetapi server perlu membatasi kompleksitas query, dan caching-nya tidak sesederhana REST.
- gRPC memakai Protocol Buffers di atas HTTP/2. Format biner dan kontrak yang ketat cocok untuk komunikasi antar-service, tetapi pemakaian dari browser membutuhkan lapisan tambahan seperti gRPC-Web.
- WebSocket membuka kanal dua arah yang tetap terbuka. Cocok untuk chat, notifikasi, dan pembaruan langsung, dengan konsekuensi server harus mengelola banyak koneksi aktif.
4. Autentikasi API
Bagian ini paling sering saya perhatikan, karena keamanan perlu dipikirkan sejak desain, bukan ditambal setelah ada insiden.
Pertama, bedakan dua hal: autentikasi memastikan siapa pemanggilnya, sedangkan otorisasi menentukan apa yang boleh dilakukan pemanggil tersebut. Keduanya wajib.
- Basic Auth mengirim username dan password yang di-encode Base64 pada setiap request. Base64 bukan enkripsi; siapa pun yang menangkap request dapat langsung membacanya. Karena itu, metode ini wajib digunakan melalui HTTPS.
- Token atau API key dikirim, misalnya, melalui header
Authorization: Bearer <token>. Siapa pun yang memegang token dapat memakainya, sehingga token perlu dijaga, dibatasi masa berlakunya, dan dapat dicabut.
- JWT (JSON Web Token) adalah token berisi klaim yang ditandatangani. Server dapat memverifikasinya tanpa query ke database. Namun, JWT yang ditandatangani tidak terenkripsi dan sulit dicabut sebelum kedaluwarsa. Data rahasia tidak boleh disimpan di payload-nya.
- OAuth 2.0 adalah kerangka otorisasi yang memungkinkan aplikasi memperoleh akses terbatas ke resource milik pengguna tanpa mengetahui password-nya, contohnya fitur “Login with Google”. Untuk identitas pengguna, OAuth umumnya dipasangkan dengan OpenID Connect.
- Session menyimpan status login di server, sedangkan browser hanya memegang ID session melalui cookie. Session mudah dicabut, tetapi membutuhkan perlindungan terhadap CSRF dan penyimpanan session yang dapat dibagi antar-instance.
5. Dokumentasi API
API yang baik dapat dipahami tanpa harus membuka kode server-nya. Dokumentasi minimal memuat endpoint, parameter, contoh request–response, kode error, dan cara autentikasi.
- OpenAPI adalah spesifikasi standar untuk mendeskripsikan HTTP API. Swagger adalah nama lama spesifikasi tersebut dan kini menjadi nama rangkaian tools seperti Swagger UI dan Swagger Editor.
- Postman digunakan untuk mencoba request, menyimpan koleksi, dan menerbitkan dokumentasi dari koleksi tersebut.
- Redoc menampilkan dokumen OpenAPI sebagai halaman referensi yang rapi.
- DapperDox menggabungkan spesifikasi OpenAPI dengan dokumentasi tambahan berbasis Markdown.
Saya menyarankan dokumentasi dihasilkan dari spesifikasi atau dari kode, lalu dimasukkan ke pipeline. Dokumen yang ditulis terpisah hampir selalu tertinggal dari implementasinya.
6. Fitur API
- Pagination membagi data besar menjadi beberapa halaman. Offset pagination (
?page=2&limit=20) mudah dibuat, sedangkan cursor pagination lebih stabil ketika data sering berubah.
- Parameter dapat berada di path (
/users/42), query string (?status=active), header, atau body. Apa pun sumbernya, semua input dari client wajib divalidasi.
- Idempotency berarti request yang sama dapat diulang tanpa menimbulkan efek tambahan.
GET,PUT, danDELETEdidefinisikan idempotent, sedangkanPOSTtidak. Untuk operasi seperti pembayaran, banyak API memakai headerIdempotency-Keyagar retry tidak membuat transaksi ganda.
- Versioning menjaga client lama tetap berjalan ketika kontrak berubah, misalnya melalui path
/v1/ordersatau header. Perubahan yang merusak kompatibilitas membutuhkan versi baru dan masa transisi.
- HATEOAS menyertakan link ke aksi atau resource terkait di dalam response, sehingga client dapat menavigasi API dari response tersebut. Konsep ini merupakan bagian dari REST menurut Roy Fielding, walaupun jarang diterapkan secara penuh.
- Content negotiation memungkinkan client meminta format tertentu melalui header
Accept, misalnya JSON atau XML, lalu server memilih representasi yang tersedia.
7. Teknik Performa API
- Caching dapat dilakukan di client, CDN, gateway, atau aplikasi. Tantangan utamanya bukan menyimpan data, melainkan menentukan kapan cache harus dianggap usang.
- Rate limiting membatasi jumlah request per client dalam periode tertentu. Server umumnya membalas
429 Too Many Requestsdan dapat menyertakan headerRetry-After. Selain menjaga performa, rate limiting juga menjadi lapisan perlindungan dari penyalahgunaan.
- Load balancing membagi request ke beberapa instance agar beban tersebar dan satu instance yang gagal tidak menghentikan layanan.
- Pagination mencegah satu response memuat data yang terlalu besar.
- Database indexing mempercepat query yang sering digunakan, tetapi setiap index menambah biaya penulisan dan penyimpanan. Index perlu ditambahkan berdasarkan pola query yang nyata, bukan perkiraan.
- Scaling dapat dilakukan secara vertikal dengan memperbesar resource mesin, atau horizontal dengan menambah instance. Scaling horizontal jauh lebih mudah bila service tidak menyimpan state di memori lokal.
- Performance testing dengan k6, JMeter, atau Gatling membantu mengukur latency dan throughput sebelum masalah muncul di production.
Prinsipnya: ukur terlebih dahulu, baru optimasi. Tanpa data latency dan profil query, optimasi mudah diarahkan ke bagian yang bukan sumber masalah.
8. API Gateway
API gateway berada di depan service dan menjadi pintu masuk request. Routing, autentikasi, rate limiting, logging, dan transformasi request sering dipusatkan di sini.
- Amazon API Gateway adalah layanan terkelola di AWS.
- Azure API Management adalah layanan pengelolaan API di Microsoft Azure (pada gambar tertulis “Azure API Services”).
- Kong adalah gateway open source berbasis Nginx dengan ekosistem plugin.
- Nginx pada dasarnya adalah web server dan reverse proxy, tetapi sering dikonfigurasi sebagai gateway sederhana.
Dari sisi infrastruktur, gateway adalah titik yang dilalui semua request. Karena itu, gateway perlu dibuat redundan, dipantau, dan tidak dijadikan tempat logika bisnis.
9. Framework Implementasi API
- Node.js dengan Express, Fastify, atau NestJS cocok untuk API JavaScript/TypeScript dengan beban I/O tinggi.
- Spring (terutama Spring Boot) banyak digunakan pada aplikasi Java skala enterprise.
- Flask adalah micro-framework Python yang ringan dan fleksibel.
- Django adalah framework Python yang lengkap. Untuk API, Django umumnya dipasangkan dengan Django REST Framework.
- FastAPI adalah framework Python modern berbasis type hints yang dapat menghasilkan dokumentasi OpenAPI secara otomatis.
Framework adalah bagian yang paling mudah diganti. Konsep pada topik-topik sebelumnya berlaku di semua framework. Pilihannya sebaiknya disesuaikan dengan bahasa yang dikuasai tim dan ekosistem yang dibutuhkan.
10. Pola Integrasi API
- Gateway menyatukan akses ke banyak service melalui satu pintu masuk.
- Event-driven membuat service menerbitkan event ke message broker seperti Kafka atau RabbitMQ, lalu service lain bereaksi tanpa saling memanggil secara langsung. Ketergantungan antar-service berkurang, tetapi alur data menjadi lebih sulit ditelusuri.
- Webhook membuat server mengirim HTTP request ke URL milik client ketika suatu peristiwa terjadi, misalnya notifikasi pembayaran berhasil. Penerima wajib memverifikasi signature dan siap menerima event yang sama lebih dari sekali.
- Polling membuat client memeriksa perubahan secara berkala. Implementasinya sederhana, tetapi boros bila data jarang berubah.
- Batch processing memproses data dalam jumlah besar pada waktu tertentu, misalnya sinkronisasi laporan setiap malam.
Penutup
Roadmap ini bukan daftar untuk dihafal. Jika memulai dari nol, urutan yang saya sarankan adalah: pahami HTTP dan REST, bangun API kecil dengan satu framework, tambahkan autentikasi dan dokumentasi, lalu jalankan melalui pipeline dengan pengujian otomatis.
Topik performa, gateway, dan pola integrasi baru benar-benar terasa ketika API sudah digunakan oleh client sungguhan. Pada tahap itu terlihat bahwa API bukan sekadar kode endpoint, melainkan juga infrastruktur, keamanan, dan cara semua bagian tersebut tersambung menjadi satu sistem yang utuh.