20 Konsep API yang Wajib Diketahui Setiap Software Engineer

1. Endpoint

Endpoint adalah URL spesifik — dikombinasikan dengan metode HTTP — yang mewakili operasi atau sumber daya tertentu dalam API. Ini adalah titik masuk tempat klien berinteraksi dengan server. Ketika aplikasi seluler ingin mengambil profil pengguna, aplikasi tersebut mengirimkan permintaan ke endpoint tertentu. Ketika ingin memperbarui profil tersebut, aplikasi menggunakan endpoint yang berbeda (atau URL yang sama dengan metode HTTP yang berbeda). Ketika ingin menghapus profil, aplikasi menggunakan endpoint lain lagi.

Konsep endpoint mencakup alamat dan operasi secara bersamaan. URL saja bukanlah endpoint — tetapi GET [URL] dan DELETE [URL] adalah dua endpoint berbeda yang kebetulan memiliki URL yang sama. Perbedaan ini penting karena API yang dirancang dengan baik mengatur endpoint mereka berdasarkan sumber daya dan operasi, bukan hanya alamat.

Dalam API REST, endpoint diatur berdasarkan kata benda (sumber daya) daripada kata kerja. Alih-alih memiliki endpoint seperti /getUser atau /deleteUser, API REST memiliki sumber daya /users/{id} dan menggunakan metode HTTP untuk menyatakan operasi apa yang akan dilakukan padanya. Desain berorientasi sumber daya ini membuat API lebih mudah diprediksi dan dipahami karena klien dapat menerapkan model mental yang sama untuk setiap sumber daya dalam sistem.

2. HTTP Method

HTTP Method adalah tindakan yang dapat dilakukan klien pada suatu sumber daya. Metode ini memberikan makna pada permintaan di luar sekadar mengidentifikasi sumber daya mana yang ditargetkan. Spesifikasi HTTP mendefinisikan sejumlah metode, tetapi lima metode utama dalam desain API adalah: GET, POST, PUT, PATCH, dan DELETE.

GET mengambil sumber daya tanpa memodifikasinya. Permintaan GET ke /users/123 mengembalikan pengguna dengan ID 123. Permintaan GET harus aman — permintaan tersebut tidak boleh menyebabkan efek samping pada server. POST membuat sumber daya baru atau memicu operasi yang tidak sesuai dengan metode lain. Permintaan POST ke /users membuat pengguna baru dengan data dalam isi permintaan. PUT mengganti seluruh sumber daya dengan data yang diberikan dalam badan permintaan. Permintaan PUT ke /users/123 mengganti seluruh catatan pengguna dengan ID 123 dengan data dalam badan permintaan. PATCH memodifikasi sumber daya sebagian, hanya memperbarui bidang yang ditentukan dalam badan permintaan daripada mengganti seluruh sumber daya. DELETE menghapus sumber daya. Permintaan DELETE ke /users/123 menghapus pengguna dengan ID tersebut.

3. Request-Response

Siklus request-response adalah pola komunikasi fundamental HTTP dan API yang dibangun di atasnya. Klien mengirimkan permintaan ke server, server memprosesnya, dan server mengembalikan respons. Semua hal lain dalam konsep API yang dibahas dalam panduan ini beroperasi di dalam atau di atas pertukaran dasar ini.

HTTP request memiliki beberapa komponen. Baris permintaan menentukan metode, URL target, dan versi HTTP. Header adalah pasangan key-value yang membawa metadata tentang permintaan — header Content-Type memberi tahu server format apa yang digunakan dalam isi permintaan, header Authorization membawa kredensial, header Accept memberi tahu server format respons apa yang dapat ditangani klien, dan header User-Agent mengidentifikasi perangkat lunak klien. Isi (ada untuk POST, PUT, dan PATCH tetapi tidak untuk GET atau DELETE) berisi data yang dikirim klien ke server, biasanya dikodekan sebagai JSON.

HTTP response mencerminkan struktur ini. Baris status mencakup versi HTTP dan kode status. Header membawa metadata tentang respons — Content-Type memberi tahu klien format isi respons, Cache-Control memberi tahu cache cara menangani respons, ETag memberikan sidik jari dari status sumber daya saat ini, dan Location memberi tahu klien di mana menemukan sumber daya yang baru dibuat. Isi respons berisi data respons yang sebenarnya.

4. Status Code

Status Code HTTP adalah angka tiga digit yang memberi tahu klien hasil dari permintaan mereka. Kode-kode ini dikelompokkan menjadi lima kelas berdasarkan digit pertama, dan setiap kelas mengkomunikasikan jenis hasil yang pada dasarnya berbeda.

Kode 2xx menunjukkan keberhasilan. 200 OK adalah yang paling umum — permintaan dipahami dan isi respons berisi data yang diminta. Kode 3xx menunjukkan pengalihan — klien perlu melakukan tindakan tambahan untuk menyelesaikan permintaan. 301 Moved Permanently memberi tahu klien bahwa sumber daya yang diminta telah dipindahkan ke URL baru dan semua permintaan di masa mendatang harus menggunakan URL baru tersebut. Kode 4xx menunjukkan kesalahan klien — permintaan salah format, tidak sah, atau tidak valid. Kode 400 Bad Request berarti server tidak dapat memahami permintaan karena sintaks yang tidak valid. Kode 5xx menunjukkan kesalahan server — server gagal memenuhi permintaan yang valid. Kode 500 Internal Server Error adalah kode umum untuk kegagalan server yang tidak terduga.

5. Authentication

Authentication adalah proses verifikasi identitas klien yang membuat permintaan ke API. Ini menjawab pertanyaan: "Siapa Anda?" Sebelum API dapat membuat keputusan tentang apa yang diizinkan untuk dilakukan klien, API perlu menetapkan siapa klien tersebut. Authentication adalah mekanisme yang menetapkan identitas tersebut.

Perbedaan antara authentication dan authorization memang halus tetapi sangat penting. Authentication menentukan identitas. Authorization menentukan izin. Keduanya merupakan hal yang terpisah dan bekerja secara berurutan, yaitu permintaan pertama-tama diotentikasi (identitas ditetapkan) dan kemudian diotorisasi (izin diperiksa). Menggabungkan keduanya dalam implementasi menciptakan kerentanan keamanan dan membuat sistem lebih sulit dipahami.

Bentuk otentikasi paling dasar adalah Basic Authentication, di mana klien mengirimkan nama pengguna dan kata sandi yang dikodekan dalam Base64 di header Authorization dengan setiap permintaan. Ini sederhana tetapi memiliki implikasi keamanan yang signifikan — kredensial dikirimkan dengan setiap permintaan, dan jika koneksi tidak dienkripsi dengan HTTPS, kredensial tersebut dapat dicegat. Basic Authentication hanya cocok untuk integrasi server-ke-server sederhana di mana kredensial dikontrol dengan baik dan HTTPS dijamin.

6. Authorization

Authorization menentukan apa yang diizinkan untuk dilakukan oleh klien yang telah diautentikasi. Setelah API menetapkan siapa yang membuat permintaan, otorisasi menentukan apakah klien tersebut memiliki izin untuk melakukan operasi yang diminta pada sumber daya yang diminta. Otentikasi dan otorisasi harus berhasil agar permintaan dapat diproses.

Model otorisasi yang paling sederhana adalah role-based access control (RBAC), di mana setiap pengguna diberi satu atau lebih peran (admin, editor, penampil, dukungan) dan setiap peran memberikan serangkaian izin (membuat pengguna, membaca postingan, menghapus komentar). Ketika permintaan tiba, API memeriksa peran pengguna yang telah diautentikasi dan menentukan apakah ada di antara peran tersebut yang memberikan izin yang diperlukan untuk operasi yang diminta.

RBAC bekerja dengan baik untuk kontrol akses yang kasar, tetapi kesulitan dengan skenario yang lebih detail. Pertanyaan "dapatkah pengguna A menghapus postingan pengguna B?" tidak dapat dijawab hanya dengan peran saja — itu bergantung pada hubungan antara pengguna tertentu dan sumber daya tertentu. Attribute-based access control (ABAC) mengatasi hal ini dengan mengevaluasi keputusan akses terhadap serangkaian faktor yang lebih kaya: atribut subjek (siapa mereka), atribut sumber daya (apa yang mereka coba akses), tindakan yang dilakukan (apa yang mereka coba lakukan), dan atribut kontekstual (waktu, lokasi, perangkat).

7. Access Token

Access token adalah kredensial yang mewakili identitas terautentikasi dalam suatu sistem, biasanya dikeluarkan setelah peristiwa autentikasi yang berhasil dan digunakan dalam permintaan selanjutnya sebagai pengganti kredensial asli. Token ini berada di persimpangan antara autentikasi dan otorisasi, sehingga membawa bukti identitas dan ruang lingkup izin yang diberikan.

Format yang paling banyak digunakan untuk access token dalam API modern adalah JSON Web Token (JWT). JWT adalah string yang terdiri dari tiga bagian yang dikodekan Base64URL yang dipisahkan oleh titik, yaitu header, payload, dan tanda tangan. Header menentukan jenis token dan algoritma penandatanganan. Payload berisi klaim, yaitu pernyataan tentang subjek (biasanya pengguna) dan metadata tentang token, termasuk siapa yang menerbitkannya (iss), siapa yang dituju (aud), kapan kadaluarsa (exp), dan pengidentifikasi pengguna (sub). Tanda tangan dihitung dengan melakukan hashing header dan payload dengan kunci rahasia (untuk tanda tangan berbasis HMAC) atau dengan menandatangani menggunakan kunci pribadi (untuk tanda tangan RSA atau ECDSA).

8. OAuth 2.0

OAuth 2.0 adalah kerangka kerja otorisasi yang memungkinkan aplikasi untuk mendapatkan akses terbatas ke akun pengguna pada layanan pihak ketiga tanpa pengguna membagikan kredensial mereka dengan aplikasi. Ini memecahkan masalah spesifik dan penting, yaitu bagaimana pengguna dapat memberikan akses aplikasi ke data mereka di layanan lain tanpa memberikan kata sandi mereka untuk layanan tersebut kepada aplikasi?

Tanpa OAuth, pendekatan umum (dan sangat cacat) adalah meminta pengguna untuk memasukkan nama pengguna dan kata sandi mereka untuk layanan pihak ketiga dan menggunakan kredensial tersebut untuk bertindak atas nama mereka. Ini bermasalah karena banyak alasan, seperti pengguna harus mempercayai aplikasi dengan kredensial mereka, aplikasi harus menyimpan kredensial tersebut dengan aman, aplikasi biasanya mendapatkan akses lebih dari yang dibutuhkan, dan mencabut akses aplikasi memerlukan perubahan kata sandi pengguna pada layanan pihak ketiga.

OAuth 2.0 memecahkan masalah ini melalui alur berbasis pengalihan di mana pengguna melakukan autentikasi langsung dengan layanan pihak ketiga (bukan dengan aplikasi), dan layanan tersebut mengeluarkan token kepada aplikasi yang memberikan akses terbatas dan terlingkup ke akun pengguna. Kata sandi pengguna tidak pernah menyentuh aplikasi. Akses dibatasi pada cakupan tertentu (membaca email, melihat daftar repositori, mengakses kalender). Dan akses dapat dicabut oleh pengguna atau layanan tanpa mengubah kata sandi apa pun.

9. Rate Limiting

Rate limiting adalah praktik membatasi jumlah permintaan yang dapat dilakukan klien ke API dalam jangka waktu tertentu. Ini adalah salah satu mekanisme terpenting untuk melindungi API dari penyalahgunaan, memastikan alokasi sumber daya yang adil di antara semua klien, dan mencegah satu klien yang berperilaku buruk menurunkan kualitas layanan untuk semua orang.

Kebutuhan akan rate limiting langsung terasa intuitif, yaitu API yang menerima permintaan tak terbatas dari klien mana pun rentan terhadap kelebihan beban yang tidak disengaja atau disengaja. Klien yang bermasalah yang memasuki loop percobaan ulang tak terbatas, penyerang yang mencoba menghitung akun pengguna melalui serangan brute force, pengumpul data yang memanggil setiap endpoint secepat server merespons — klien-klien ini dapat membanjiri sumber daya server, meningkatkan biaya infrastruktur, dan menyebabkan latensi permintaan melonjak untuk semua klien lainnya.

Rate limiting biasanya diimplementasikan pada satu atau lebih dimensi berikut, seperti berdasarkan alamat IP (membatasi jumlah permintaan dari satu IP terlepas dari klien atau pengguna mana pun), berdasarkan kunci API (membatasi jumlah permintaan per klien terdaftar), berdasarkan pengguna (membatasi jumlah permintaan per pengguna yang terautentikasi), atau berdasarkan endpoint (menerapkan batasan yang lebih ketat pada endpoint yang mahal daripada yang murah).

10. Throttling

Throttling berkaitan dengan rate limiting tetapi menangani dimensi masalah yang berbeda. Jika rate limiting membatasi jumlah total permintaan dalam jangka waktu tertentu, throttling mengontrol kecepatan permintaan, yaitu memperlambat pemrosesan daripada menolak permintaan yang melebihi batas. Kedua mekanisme ini saling melengkapi dan sering digunakan bersama.

Rate limiter mengatakan "setelah 100 permintaan dalam satu menit, tolak semua permintaan selanjutnya hingga jangka waktu diatur ulang." Throttler mengatakan "proses permintaan dengan kecepatan terkontrol terlepas dari berapa banyak yang datang" — misalnya, memproses paling banyak 10 permintaan per detik dengan mengantrekan permintaan berlebih dan melepaskannya dengan kecepatan terkontrol. Throttling tepat dilakukan ketika tujuannya adalah untuk meratakan pola permintaan yang bergelombang dan melindungi layanan hilir dari lonjakan tiba-tiba daripada untuk memberlakukan batasan keras pada total penggunaan.

Throttling juga muncul dalam konteks perlindungan layanan hilir. Ketika API bergantung pada database atau layanan pihak ketiga yang memiliki kapasitas terbatas, API dapat membatasi laju pemrosesan permintaannya sendiri untuk menghindari membebani ketergantungan tersebut. Jika layanan pemrosesan pembayaran yang bergantung pada API marketplace dapat menangani 50 permintaan per detik, API marketplace mungkin akan menyimpan token internal untuk permintaan pembayaran dan mengantrekan atau menunda permintaan yang melebihi tingkat tersebut daripada meneruskan semuanya ke layanan pembayaran secara bersamaan.

11. Pagination

Pagination atau paginasi adalah mekanisme untuk membagi kumpulan hasil yang besar menjadi bagian-bagian yang mudah dikelola yang dapat diambil secara berurutan. Tanpa paginasi, permintaan ke /users pada platform dengan sepuluh juta pengguna akan mencoba mengembalikan semua sepuluh juta catatan dalam satu respons, sehingga memenuhi bandwidth jaringan, menghabiskan memori server, dan membuat respons membutuhkan waktu yang sangat lama sehingga praktis tidak dapat digunakan.

Pendekatan paginasi yang paling dasar adalah paginasi berbasis offset, di mana klien menentukan posisi awal (offset) dan ukuran halaman (limit). Permintaan ke /users?offset=100&limit=20 mengembalikan 20 pengguna mulai dari posisi 100. Ini mudah diimplementasikan dan mudah dipahami oleh klien, dan memungkinkan klien untuk langsung melompat ke halaman mana pun dengan menghitung offset yang sesuai. Kelemahannya adalah kinerja pada offset besar: kueri database dengan OFFSET 1000000 LIMIT 20 harus memindai dan membuang satu juta catatan untuk menemukan posisi awal, yang dapat sangat lambat pada kumpulan data besar.

Paginasi berbasis kursor mengatasi masalah kinerja ini. Alih-alih offset, klien menerima kursor buram — biasanya representasi yang dikodekan Base64 dari pengidentifikasi catatan terakhir pada halaman saat ini — yang diteruskan untuk mendapatkan halaman berikutnya. Server menggunakan kursor ini untuk menemukan titik awal secara efisien: WHERE id > :cursor ORDER BY id LIMIT 20 dapat menggunakan indeks pada id untuk menemukan halaman berikutnya tanpa memindai catatan sebelumnya, terlepas dari seberapa dalam kita berada dalam dataset. Kelemahannya adalah paginasi berbasis kursor tidak mendukung akses acak ke halaman sembarang, sehingga kita hanya dapat bergerak maju (atau mundur dengan kursor dua arah) melalui hasilnya.

12. Caching

Caching adalah menyimpan hasil komputasi atau permintaan sebelumnya sehingga permintaan di masa mendatang untuk data yang sama dapat dilayani dari cache daripada mengulangi komputasi atau kueri database. Ini adalah salah satu alat paling ampuh untuk meningkatkan kinerja API dan mengurangi biaya infrastruktur, dan beroperasi di berbagai lapisan sistem API tipikal.

Caching HTTP adalah lapisan yang paling dekat dengan klien dan memanfaatkan semantik caching yang dibangun ke dalam protokol HTTP. Header respons Cache-Control mengontrol bagaimana klien, proxy, dan node edge CDN menyimpan respons dalam cache. Cache-Control: public, max-age=3600 memberi tahu semua cache bahwa respons dapat disimpan dan digunakan kembali hingga satu jam. Cache-Control: private, max-age=300 memberi tahu cache bahwa respons tersebut khusus untuk satu pengguna dan tidak boleh disimpan dalam cache bersama (seperti CDN). Cache-Control: no-store memberi tahu semua cache untuk tidak pernah menyimpan respons ini. Cache-Control: no-cache sedikit berbeda — ini memungkinkan penyimpanan tetapi memerlukan validasi ulang dengan server asal sebelum digunakan. ETag (Entity Tags) dan permintaan bersyarat memungkinkan validasi ulang cache yang efisien. Ketika server mengembalikan respons, server dapat menyertakan header ETag yang berisi sidik jari (biasanya hash) dari isi respons. Ketika entri cache klien kedaluwarsa, alih-alih mengambil respons lengkap lagi, klien dapat mengirim permintaan bersyarat dengan header If-None-Match: . Jika sumber daya belum berubah, server mengembalikan 304 Not Modified tanpa isi — menghemat bandwidth — dan klien terus menggunakan salinan cache-nya. Mekanisme ini memungkinkan cache untuk diperbarui secara efisien bahkan untuk respons yang besar.

13. Idempotency

Idempotency adalah sifat suatu operasi di mana pelaksanaannya beberapa kali memiliki efek yang sama dengan pelaksanaannya sekali. Suatu operasi bersifat idempoten jika keadaan sistem setelah menjalankannya sekali identik dengan keadaan setelah menjalankannya sepuluh kali. Sifat ini sangat penting untuk membangun sistem terdistribusi yang andal di mana kegagalan jaringan, waktu habis, dan percobaan ulang adalah kondisi operasi normal.

Pentingnya idempotensi secara praktis terlihat jelas dalam skenario kegagalan. Pertimbangkan klien yang mengirimkan permintaan POST untuk membuat pesanan dan server memproses permintaan tersebut dan membuat pesanan, tetapi respons hilang karena kegagalan jaringan sebelum mencapai klien. Klien tidak tahu apakah pesanan telah dibuat — klien hanya tahu bahwa ia tidak menerima respons. Jika klien mencoba kembali permintaan tersebut (yang dipersyaratkan oleh kebijakan percobaan ulang yang bertanggung jawab), dan POST tidak idempoten, pesanan kedua akan dibuat. Klien sekarang memiliki dua pesanan padahal yang diinginkannya hanya satu.

GET, HEAD, PUT, dan DELETE semuanya idempoten menurut spesifikasi HTTP. POST dan PATCH tidak demikian, itulah sebabnya pola kunci idempotensi paling sering diterapkan pada permintaan POST untuk pembuatan sumber daya dan operasi keuangan.

14. Webhook

Webhook adalah mekanisme bagi API untuk memberi tahu klien tentang peristiwa secara real-time, alih-alih mengharuskan klien untuk secara berkala melakukan polling untuk pembaruan. Alih-alih klien berulang kali bertanya "apakah ada yang berubah?", server mengirimkan pemberitahuan ke klien segera ketika sesuatu terjadi. Pembalikan model permintaan-respons ini — di mana server memulai kontak dengan klien, bukan sebaliknya — inilah yang membuat webhook menjadi ampuh.

Model webhook bekerja sebagai berikut. Klien mendaftarkan endpoint webhook ke server, yaitu memberikan URL tempat server harus mengirimkan pemberitahuan, dan biasanya menentukan jenis peristiwa apa yang ingin diterimanya. Ketika suatu peristiwa terjadi (pembayaran diterima, penyebaran selesai, pesan baru tiba), server membuat permintaan HTTP POST ke URL yang terdaftar dengan payload yang menjelaskan peristiwa tersebut. Handler webhook klien menerima permintaan ini, memproses peristiwa tersebut, dan merespons dengan status 200 untuk mengakui penerimaan.

15. API Versioning

API versioning adalah praktik mengelola perubahan pada API sedemikian rupa sehingga klien dapat terus berfungsi dengan benar seiring evolusi API. Ini adalah salah satu topik yang paling kontroversial dalam desain API karena ada ketegangan nyata antara kebutuhan penyedia API (yang ingin mengembangkan API mereka tanpa dibatasi oleh kompatibilitas mundur) dan konsumen API (yang menginginkan stabilitas dan prediktabilitas dalam API yang mereka andalkan).

Tantangan mendasar adalah bahwa setelah API diimplementasikan dan klien bergantung padanya, mengubahnya akan merusak klien tersebut. Menghapus bidang dari respons yang diandalkan klien, mengganti nama endpoint, mengubah arti parameter, atau menambahkan bidang yang diperlukan ke permintaan semuanya dapat menyebabkan integrasi klien gagal. Pengelolaan versi adalah mekanisme untuk mengelola ketegangan ini dengan memungkinkan perilaku lama dan baru untuk hidup berdampingan.

16. OpenAPI

Spesifikasi OpenAPI (sebelumnya dikenal sebagai Swagger) adalah format standar untuk mendeskripsikan API REST dengan cara yang dapat dibaca mesin. Dokumen OpenAPI — biasanya ditulis dalam YAML atau JSON — mendeskripsikan setiap endpoint, parameter, badan permintaan, skema respons, metode otentikasi, dan kode kesalahan API dalam format terstruktur yang dapat diproses oleh manusia dan alat.

Nilai OpenAPI meluas ke beberapa arah secara bersamaan. Untuk dokumentasi, dokumen OpenAPI dapat dirender menjadi dokumentasi referensi interaktif di mana developer dapat membaca tentang endpoint, memahami parameter dan format responsnya, dan mengujinya langsung di browser. Alat seperti Swagger UI dan Redoc menghasilkan dokumentasi ini secara otomatis dari spesifikasi OpenAPI, sehingga menghilangkan kebutuhan untuk menulis dan memelihara dokumentasi secara terpisah dari implementasi API.

Untuk pembuatan klien, OpenAPI memungkinkan pembuatan pustaka klien secara otomatis dalam berbagai bahasa dari spesifikasi. Alih-alih developer menulis klien HTTP untuk API secara manual, mereka dapat membuatnya menggunakan alat seperti OpenAPI Generator dan mendapatkan klien yang diketik dan idiomatik yang mengabstraksi detail HTTP. Hal ini secara dramatis mengurangi upaya untuk menggunakan API baru dan memastikan bahwa klien selalu konsisten dengan spesifikasi.

Untuk validasi sisi server, spesifikasi dapat digunakan untuk memvalidasi permintaan masuk terhadap skema yang ditentukan secara otomatis, memastikan bahwa bidang yang dibutuhkan yang hilang, tipe bidang yang tidak valid, dan nilai di luar rentang ditolak sebelum mencapai logika bisnis. Alat yang mengimplementasikan validasi ini dari spesifikasi OpenAPI mengurangi jumlah kode validasi yang perlu ditulis oleh developer.

17. REST vs. GraphQL

REST (Representational State Transfer) dan GraphQL adalah dua pendekatan arsitektur yang berbeda untuk desain API, dan memahami kapan masing-masing tepat digunakan membutuhkan pemahaman tentang masalah apa yang dirancang untuk dipecahkan oleh masing-masing pendekatan.

REST adalah gaya arsitektur yang dibangun di atas model berorientasi sumber daya HTTP. Sumber daya diidentifikasi oleh URL, operasi diekspresikan melalui metode HTTP, dan representasi (biasanya JSON) dipertukarkan dalam badan permintaan dan respons. API REST dirancang di sekitar serangkaian endpoint tetap, yang masing-masing mengembalikan serangkaian data tetap untuk sumber daya tertentu. API REST untuk platform sosial mungkin memiliki /users/:id, /users/:id/posts, dan /users/:id/followers sebagai endpoint terpisah yang masing-masing mengembalikan data pengguna, postingan pengguna, dan pengikut pengguna.

GraphQL adalah bahasa kueri dan runtime untuk API yang dikembangkan oleh Facebook untuk mengatasi masalah spesifik yang mereka temui dengan REST, yaitu ketidaksesuaian antara apa yang dikembalikan oleh endpoint REST dan apa yang sebenarnya dibutuhkan klien. Dengan REST, klien sering kali harus membuat beberapa permintaan untuk mendapatkan data yang dibutuhkan untuk satu tampilan (masalah N+1), atau endpoint mengembalikan data jauh lebih banyak daripada yang dibutuhkan (over-fetching), atau klien membutuhkan data dari beberapa sumber daya yang akan membutuhkan beberapa perjalanan bolak-balik (under-fetching).

18. API Gateway

API gateway adalah server yang bertindak sebagai titik masuk tunggal untuk semua permintaan klien ke kumpulan layanan backend. Alih-alih klien berkomunikasi langsung dengan setiap layanan backend individual, semua permintaan melewati gateway, yang mengarahkannya ke layanan yang sesuai, menerapkan hal-hal lintas layanan (otentikasi, pembatasan laju, pencatatan, transformasi permintaan), dan mengembalikan respons ke klien.

Pola API gateway mengatasi beberapa masalah nyata dalam sistem berbasis API. Tanpa gateway, setiap layanan bertanggung jawab untuk menerapkan hal-hal lintas layanan yang sama: setiap layanan harus mengotentikasi permintaan, setiap layanan harus memberlakukan pembatasan laju, setiap layanan harus mencatat permintaan untuk audit. Ini menciptakan duplikasi, inkonsistensi, dan beban pemeliharaan di puluhan layanan. Gateway memusatkan hal-hal ini, menerapkannya sekali untuk semua layanan yang berada di belakangnya.

Pengarahan permintaan adalah fungsi paling mendasar dari gateway. Permintaan ke /api/users diarahkan ke Layanan Pengguna, permintaan ke /api/orders diarahkan ke Layanan Pesanan, permintaan ke /api/products diarahkan ke Layanan Produk. Perutean ini dapat didasarkan pada jalur URL, header permintaan, parameter kueri, atau kombinasi apa pun. Ini memisahkan bentuk API eksternal (apa yang dilihat klien) dari topologi layanan internal (bagaimana backend diatur), memungkinkan layanan untuk dipisahkan, digabungkan, atau diganti tanpa mengubah API eksternal.

19. Microservice

Microservice adalah gaya arsitektur di mana aplikasi besar dipecah menjadi kumpulan layanan kecil yang dapat diimplementasikan secara independen, masing-masing bertanggung jawab atas kemampuan bisnis tertentu dan berkomunikasi dengan layanan lain melalui API yang terdefinisi dengan baik. Memahami microservice sangat penting bagi setiap engineer yang bekerja pada sistem API modern karena tantangan desain API dari arsitektur microservice pada dasarnya berbeda dari — dan lebih kompleks daripada — tantangan aplikasi monolitik.

Pendekatan microservice dimotivasi oleh keterbatasan aplikasi monolitik besar saat berkembang. Dalam monolit, semua kode diimplementasikan bersama, yang berarti setiap perubahan memerlukan implementasi ulang seluruh aplikasi. Bagian-bagian sistem yang berbeda tidak dapat diskalakan secara independen — jika fungsi pemrosesan gambar sedang dalam beban, peningkatan skala memerlukan penskalaan seluruh monolit meskipun bagian lain sedang tidak aktif. Tim yang mengerjakan bagian-bagian sistem yang berbeda saling berkonflik melalui database bersama, kode bersama, dan jadwal implementasi bersama.

Microservice mengatasi keterbatasan ini melalui dekomposisi di sepanjang konteks terbatas, yaitu konsep desain berbasis domain untuk mengidentifikasi batasan alami antara berbagai area fungsi bisnis. Platform ritel dapat dipecah menjadi layanan untuk Katalog Produk, Inventaris, Harga, Keranjang Belanja, Pesanan, Pemenuhan Pesanan, Pembayaran, Akun Pengguna, dan Notifikasi. Setiap layanan memiliki penyimpanan datanya sendiri, pipeline penyebarannya sendiri, dan timnya sendiri. Mereka berkomunikasi melalui API — secara sinkron melalui HTTP/REST atau gRPC, secara asinkron melalui antrian pesan dan aliran peristiwa.

20. Error Handling

Error handling adalah praktik mendesain API untuk mengkomunikasikan kegagalan secara jelas, konsisten, dan dengan informasi yang cukup sehingga klien dapat memahami apa yang salah dan apa yang dapat mereka lakukan, jika ada. Ini adalah salah satu aspek desain API yang paling tidak glamor dan salah satu yang terpenting untuk pengalaman developer bagi siapa pun yang membangun API kita.

Dasar dari penanganan kesalahan API yang baik adalah penggunaan kode status HTTP yang benar, yang dibahas dalam konsep 4. Tetapi kode status saja tidak cukup — kode tersebut memberi tahu klien kategori kesalahan tetapi bukan detail spesifiknya. Kode 400 Bad Request dapat berarti bidang yang diperlukan hilang, nilai bidang tidak valid, pelanggaran aturan bisnis, atau ratusan masalah lainnya. Klien membutuhkan informasi yang lebih spesifik untuk menangani kesalahan secara terprogram.

Format respons kesalahan yang konsisten sangat penting. Alih-alih setiap endpoint mengembalikan kesalahan dalam format yang berbeda, API harus mengembalikan respons kesalahan dalam satu struktur yang terdokumentasi di semua endpoint. Struktur respons kesalahan yang umum dan praktis mencakup kode kesalahan yang dapat dibaca mesin (konstanta string seperti INVALID_EMAIL atau INSUFFICIENT_FUNDS), pesan yang dapat dibaca manusia yang menjelaskan masalah dalam bahasa yang sederhana, dan secara opsional array detail untuk kesalahan validasi yang mencantumkan setiap bidang dengan kesalahan spesifiknya.

Jadi, dua puluh konsep ini membentuk kosakata desain dan pengembangan API. Konsep-konsep ini bukanlah ide yang berdiri sendiri, tetapi konsep-konsep ini saling terkait dan bergantung satu sama lain dengan cara yang akan menjadi lebih jelas saat kita membangun dan memelihara sistem nyata.