Bagikan melalui

Praktik terbaik untuk desain API web RESTful

Implementasi API web RESTful adalah API web yang menggunakan prinsip arsitektur Representational State Transfer (REST) untuk mencapai antarmuka stateless dan digabungkan secara longgar antara klien dan layanan. API web yang RESTful mendukung protokol HTTP standar untuk melakukan operasi pada sumber daya dan mengembalikan representasi sumber daya yang berisi tautan hypermedia dan kode status operasi HTTP.

API web RESTful harus selaras dengan prinsip-prinsip berikut:

  • Independensi platform, yang berarti bahwa klien dapat memanggil API web terlepas dari implementasi internal. Untuk mencapai kemandirian platform, API web menggunakan HTTP sebagai protokol standar, menyediakan dokumentasi yang jelas, dan mendukung format pertukaran data yang familier seperti JSON atau XML.

  • Kopling longgar, yang berarti bahwa klien dan layanan web dapat berevolusi secara mandiri. Klien tidak perlu mengetahui implementasi internal layanan web, dan layanan web tidak perlu mengetahui implementasi internal klien. Untuk mencapai kopling longgar dalam API web RESTful, gunakan hanya protokol standar dan terapkan mekanisme yang memungkinkan klien dan layanan web untuk menyetujui format data yang akan ditukar.

Artikel ini menjelaskan praktik terbaik untuk merancang API web RESTful. Ini juga mencakup pola desain umum dan pertimbangan untuk membangun API web yang mudah dipahami, fleksibel, dan dapat dipertahankan.

Konsep desain API web RESTful

Untuk menerapkan API web RESTful, Anda perlu memahami konsep berikut.

  • Pengidentifikasi Sumber Daya Seragam (URI): REST API dirancang di sekitar sumber daya, yang merupakan segala jenis objek, data, atau layanan yang dapat diakses klien. Setiap sumber daya diwakili oleh URI yang secara unik mengidentifikasi sumber daya tersebut. Misalnya, URI untuk pesanan pelanggan tertentu mungkin:

    https://api.contoso.com/orders/1

  • Representasi sumber daya menentukan bagaimana sumber daya yang diidentifikasi oleh URI-nya dikodekan dan diangkut melalui protokol HTTP dalam format tertentu, seperti XML atau JSON. Klien yang ingin mengambil sumber daya tertentu harus menggunakan URI sumber daya dalam permintaan ke API. API mengembalikan representasi sumber daya dari data yang ditunjukkan URI. Misalnya, klien dapat membuat permintaan GET ke pengidentifikasi https://api.contoso.com/orders/1 URI untuk menerima isi JSON berikut:

    {"orderId":1,"orderValue":99.9,"productId":1,"quantity":1}

  • Antarmuka yang seragam adalah bagaimana API RESTful mencapai kopling longgar antara implementasi klien dan layanan. Untuk REST API yang dibangun di HTTP, antarmuka seragam mencakup penggunaan kata kerja HTTP standar untuk melakukan operasi seperti GET, , POSTPUT, PATCH, dan DELETE pada sumber daya.

  • Model permintaan stateless: API RESTful menggunakan model permintaan stateless, yang berarti bahwa permintaan HTTP independen dan mungkin terjadi dalam urutan apa pun. Untuk alasan ini, menyimpan informasi status sementara antar permintaan tidak layak. Satu-satunya tempat di mana informasi disimpan ada di sumber daya itu sendiri, dan setiap permintaan harus menjadi operasi atomik. Model permintaan stateless mendukung skalabilitas tinggi karena tidak perlu mempertahankan afinitas apa pun antara klien dan server tertentu. Namun, model stateless juga dapat membatasi skalabilitas karena tantangan dengan skalabilitas penyimpanan back-end layanan web. Untuk informasi selengkapnya tentang strategi untuk memperluas skala penyimpanan data, lihat Pemartisian data.

  • Tautan Hypermedia: REST API dapat didorong oleh tautan hypermedia yang terkandung dalam setiap representasi sumber daya. Misalnya, blok kode berikut menunjukkan representasi JSON dari pesanan. Ini berisi tautan guna mendapatkan atau memperbarui pelanggan yang terkait dengan pesanan.

    {
  "orderID":3,
  "productID":2,
  "quantity":4,
  "orderValue":16.60,
  "links": [
    {"rel":"product","href":"https://api.contoso.com/customers/3", "action":"GET" },
    {"rel":"product","href":"https://api.contoso.com/customers/3", "action":"PUT" }
  ]
}

Tentukan URI sumber daya API web RESTful

API web RESTful diatur di sekitar sumber daya. Untuk mengatur desain API Anda di sekitar sumber daya, tentukan URI sumber daya yang memetakan ke entitas bisnis. Jika memungkinkan, URI sumber daya dasar pada kata benda (sumber daya) dan bukan kata kerja (operasi pada sumber daya).

Misalnya, dalam sistem e-niaga, entitas bisnis utama mungkin pelanggan dan pesanan. Untuk membuat pesanan, klien mengirimkan informasi pesanan dalam permintaan HTTP POST ke URI sumber daya. Respons HTTP terhadap permintaan menunjukkan apakah pembuatan pesanan berhasil.

URI untuk membuat sumber daya pesanan mungkin seperti:

https://api.contoso.com/orders // Good

Hindari menggunakan kata kerja dalam URI untuk mewakili operasi. Misalnya, URI berikut tidak disarankan:

https://api.contoso.com/create-order // Avoid

Entitas sering dikelompokkan bersama ke dalam koleksi seperti pelanggan atau pesanan. Koleksi adalah sumber daya terpisah dari item di dalam koleksi, sehingga harus memiliki URI sendiri. Misalnya, URI berikut mungkin mewakili kumpulan pesanan:

https://api.contoso.com/orders

Setelah klien mengambil koleksi, klien dapat membuat permintaan GET ke URI setiap item. Misalnya, untuk menerima informasi tentang pesanan tertentu, klien melakukan permintaan HTTP GET pada URI https://api.contoso.com/orders/1 untuk menerima isi JSON berikut sebagai representasi sumber daya dari data pesanan internal:

{"orderId":1,"orderValue":99.9,"productId":1,"quantity":1}

Konvensi penamaan URI sumber daya

Saat Anda merancang API web RESTful, penting bagi Anda untuk menggunakan konvensi penamaan dan hubungan yang benar untuk sumber daya:

  • Gunakan kata benda untuk nama sumber daya. Gunakan kata benda untuk mewakili sumber daya. Misalnya, gunakan /orders, bukan /create-order. Metode HTTP GET, POST, PUT, PATCH, dan DELETE sudah menyiratkan tindakan verbal.

  • Gunakan kata benda jamak untuk memberi nama URI koleksi. Secara umum, ini membantu menggunakan kata benda jamak untuk URI yang mereferensikan koleksi. Ini adalah praktik yang baik untuk mengatur URI untuk koleksi dan item ke dalam hierarki. Misalnya, /customers adalah jalur ke koleksi pelanggan, dan /customers/5 merupakan jalur ke pelanggan dengan ID yang sama dengan 5. Pendekatan ini membantu menjaga API web tetap intuitif. Selain itu, banyak kerangka kerja API web dapat merutekan permintaan berdasarkan jalur URI berparameter, sehingga Anda dapat menentukan rute untuk jalur /customers/{id}.

  • Pertimbangkan hubungan antara berbagai jenis sumber daya dan bagaimana Anda dapat mengekspos asosiasi ini. Misalnya, /customers/5/orders mungkin mewakili semua pesanan untuk pelanggan 5. Anda juga dapat mendekati hubungan ke arah lain dengan mewakili asosiasi dari pesanan ke pelanggan. Dalam skenario ini, URI mungkin /orders/99/customer. Namun, memperluas model ini terlalu jauh dapat menjadi rumit untuk diimplementasikan. Pendekatan yang lebih baik adalah menyertakan tautan dalam isi pesan respons HTTP sehingga klien dapat dengan mudah mengakses sumber daya terkait. Gunakan Hypertext sebagai Mesin Status Aplikasi (HATEOAS) untuk memungkinkan navigasi ke sumber daya terkait menjelaskan mekanisme ini secara lebih rinci.

  • Jaga hubungan tetap sederhana dan fleksibel. Dalam sistem yang lebih kompleks, Anda mungkin cenderung menyediakan URI yang memungkinkan klien untuk menavigasi melalui beberapa tingkat hubungan, seperti /customers/1/orders/99/products. Namun, tingkat kompleksitas ini bisa sulit dipertahankan dan tidak fleksibel jika hubungan antara sumber daya berubah di masa depan. Sebagai gantinya, cobalah untuk menjaga URI relatif sederhana. Setelah aplikasi memiliki referensi ke sumber daya, Anda harus dapat menggunakan referensi ini untuk menemukan item yang terkait dengan sumber daya tersebut. Anda dapat mengganti kueri sebelumnya dengan URI /customers/1/orders untuk menemukan semua pesanan untuk pelanggan 1, lalu menggunakan /orders/99/products untuk menemukan produk dalam pesanan ini.

    Petunjuk / Saran

    Hindari memerlukan URI sumber daya yang lebih kompleks daripada koleksi/item/koleksi.

  • Hindari sejumlah besar sumber daya kecil. Semua permintaan web memberlakukan beban di server web. Semakin banyak permintaan, semakin besar bebannya. API Web yang mengekspos sejumlah besar sumber daya kecil dikenal sebagai API web yang cerewet. Cobalah untuk menghindari API ini karena memerlukan aplikasi klien untuk mengirim beberapa permintaan untuk menemukan semua data yang diperlukan. Sebagai gantinya, pertimbangkan untuk mendenormalisasi data dan menggabungkan informasi terkait ke dalam sumber daya yang lebih besar yang dapat diambil melalui satu permintaan. Namun, Anda masih perlu menyeimbangkan pendekatan ini terhadap overhead pengambilan data yang tidak dibutuhkan klien. Pengambilan objek besar dapat meningkatkan latensi permintaan dan mengakibatkan biaya bandwidth yang lebih besar. Untuk informasi selengkapnya tentang antipattern performa ini, lihat Chatty I/O dan Extraneous Fetching.

  • Hindari membuat API yang mencerminkan struktur internal database. Tujuan REST adalah untuk memodelkan entitas bisnis dan operasi yang dapat dilakukan aplikasi pada entitas tersebut. Pelanggan tidak boleh terpapar kepada implementasi internal. Misalnya, jika data Anda disimpan dalam database relasional, API web tidak perlu mengekspos setiap tabel sebagai kumpulan sumber daya. Pendekatan ini meningkatkan permukaan serangan dan dapat mengakibatkan kebocoran data. Sebagai gantinya, anggap API web sebagai abstraksi database. Jika perlu, perkenalkan lapisan pemetaan antara database dan API web. Lapisan ini memastikan bahwa aplikasi klien diisolasi dari perubahan pada skema database yang mendasar.

Petunjuk / Saran

Mungkin tidak mungkin untuk memetakan setiap operasi yang diterapkan oleh API web ke sumber daya tertentu. Anda dapat menangani skenario nonresource ini melalui permintaan HTTP yang memanggil fungsi dan mengembalikan hasilnya sebagai pesan respons HTTP.

Misalnya, API web yang menerapkan operasi kalkulator sederhana seperti menambahkan dan mengurangi dapat menyediakan URI yang mengekspos operasi ini sebagai sumber daya semu dan menggunakan string kueri untuk menentukan parameter yang diperlukan. Permintaan GET ke URI /add?operand1=99&operand2=1 mengembalikan pesan respons dengan isi yang berisi nilai 100.

Namun, Anda harus menggunakan bentuk-bentuk URI ini dengan hemat.

Tentukan metode API web RESTful

Metode API web RESTful selaras dengan metode permintaan dan jenis media yang ditentukan oleh protokol HTTP. Bagian ini menjelaskan metode permintaan yang paling umum dan jenis media yang digunakan dalam API web RESTful.

Metode permintaan HTTP

Protokol HTTP menentukan banyak metode permintaan yang menunjukkan tindakan yang ingin Anda lakukan pada sumber daya. Metode yang paling umum digunakan dalam API web RESTful adalah GET, POST, PUT, PATCH, dan DELETE. Setiap metode sesuai dengan operasi tertentu. Saat Anda merancang API web RESTful, gunakan metode ini dengan cara yang konsisten dengan definisi protokol, sumber daya yang sedang diakses, dan tindakan yang sedang dilakukan.

Penting untuk diingat bahwa efek metode permintaan tertentu harus bergantung pada apakah sumber daya adalah koleksi atau item individual. Tabel berikut mencakup beberapa konvensi yang digunakan sebagian besar implementasi RESTful.

Penting

Tabel berikut menggunakan contoh entitas e-commerce customer. API web tidak perlu menerapkan semua metode permintaan. Metode yang diterapkannya tergantung pada skenario tertentu.

Sumber daya POS DAPATKAN MELETAKKAN MENGHAPUS
/Pelanggan Membuat pelanggan baru Memperoleh semua pelanggan Pembaruan massal pelanggan Menghapus semua pelanggan
/customers/1 Kesalahan Ambil rincian untuk pelanggan 1 Perbarui detail pelanggan 1 jika ada Menghapus pelanggan 1
/customers/1/orders Membuat pesanan baru untuk pelanggan 1 Ambil semua pesanan milik pelanggan 1 Pembaruan massal pesanan untuk pelanggan 1 Menghapus semua pesanan untuk pelanggan 1

Permintaan GET

Permintaan GET mengambil representasi sumber daya di URI yang ditentukan. Isi pesan respons berisi detail sumber daya yang diminta.

Permintaan GET harus mengembalikan salah satu kode status HTTP berikut:

Kode Status HTTP Alasan
200 (OK) Metode telah berhasil mengembalikan sumber daya.
204 (Tidak Ada Konten) Isi respons tidak berisi konten apa pun, seperti ketika permintaan pencarian tidak mengembalikan kecocokan dalam respons HTTP.
404 (Tidak Ditemukan) Sumber daya yang diminta tidak dapat ditemukan.

Permintaan POST

Permintaan POST harus membuat sebuah sumber daya. Server menetapkan URI untuk sumber daya baru dan mengembalikan URI tersebut ke klien.

Penting

Untuk permintaan POST, klien tidak boleh mencoba membuat URI sendiri. Klien harus mengirimkan permintaan ke URI koleksi, dan server harus menetapkan URI ke sumber daya baru. Jika klien mencoba membuat URI sendiri dan mengeluarkan permintaan POST ke URI tertentu, server mengembalikan kode status HTTP 400 (PERMINTAAN BURUK) untuk menunjukkan bahwa metode tidak didukung.

Dalam model RESTful, permintaan POST digunakan untuk menambahkan sumber daya baru ke koleksi yang diidentifikasi URI. Namun, permintaan POST juga dapat digunakan untuk mengirimkan data untuk diproses ke sumber daya yang ada, tanpa pembuatan sumber daya baru apa pun.

Permintaan POST harus mengembalikan salah satu kode status HTTP berikut:

Kode Status HTTP Alasan
200 (OK) Metode ini telah melakukan beberapa pemrosesan tetapi tidak membuat sumber daya baru. Hasil operasi mungkin disertakan dalam isi respons.
201 (Dibuat) Sumber daya berhasil dibuat. URI sumber daya baru disertakan dalam header Lokasi respons. Isi respons berisi representasi sumber daya.
204 (Tidak Ada Konten) Isi respons tidak berisi konten.
400 (Permintaan Tidak Valid) Klien telah menempatkan data yang tidak valid dalam permintaan. Isi respons dapat berisi informasi selengkapnya tentang kesalahan atau tautan ke URI yang memberikan detail selengkapnya.
405 (Metode Tidak Diizinkan) Klien telah mencoba membuat permintaan POST ke URI yang tidak mendukung permintaan POST.

Permintaan PUT

Permintaan PUT harus memperbarui sumber daya yang ada jika ada atau, dalam beberapa kasus, membuat sumber daya baru jika tidak ada. Untuk membuat permintaan PUT:

  1. Klien menentukan URI untuk sumber daya dan menyertakan isi permintaan yang berisi representasi lengkap sumber daya.
  2. Klien membuat permintaan.
  3. Jika sumber daya yang memiliki URI ini sudah ada, sumber daya akan diganti. Jika tidak, sumber daya baru dibuat, jika rute mendukungnya.

Metode PUT diterapkan ke sumber daya yang merupakan item individual, seperti pelanggan tertentu, bukan koleksi. Server mungkin mendukung pembaruan tetapi tidak mendukung pembuatan melalui PUT. Apakah mendukung pembuatan melalui PUT tergantung pada apakah klien dapat menetapkan URI secara bermakna dan andal ke sumber daya sebelum ada. Jika tidak bisa, gunakan POST untuk membuat sumber daya dan minta server menetapkan URI. Kemudian gunakan PUT atau PATCH untuk memperbarui URI.

Penting

Permintaan PUT harus idempogen, yang berarti bahwa mengirimkan permintaan yang sama beberapa kali selalu menghasilkan sumber daya yang sama yang dimodifikasi dengan nilai yang sama. Jika klien mengirim ulang permintaan PUT, hasilnya harus tetap tidak berubah. Sebaliknya, permintaan POST dan PATCH tidak dijamin bersifat idempoten.

Permintaan PUT harus mengembalikan salah satu kode status HTTP berikut:

Kode Status HTTP Alasan
200 (OK) Sumber daya berhasil diperbarui.
201 (Dibuat) Sumber daya berhasil dibuat. Isi respons mungkin berisi representasi sumber daya.
204 (Tidak Ada Konten) Sumber daya berhasil diperbarui, tetapi isi respons tidak berisi konten apa pun.
409 (Konflik) Permintaan tidak dapat diselesaikan karena konflik dengan status sumber daya saat ini.

Petunjuk / Saran

Pertimbangkan untuk menerapkan operasi HTTP PUT massal yang dapat membuat batch pembaruan ke beberapa sumber daya dalam koleksi. Permintaan PUT harus menentukan URI koleksi. Isi permintaan harus menentukan detail sumber daya yang akan dimodifikasi. Pendekatan ini dapat membantu mengurangi obrolan dan meningkatkan performa.

Permintaan PATCH (untuk memperbarui sebagian data)

Permintaan PATCH melakukan pembaruan parsial ke sumber daya yang ada. Klien menentukan URI untuk sumber daya. Isi permintaan menentukan serangkaian perubahan yang akan diterapkan ke sumber daya. Metode ini bisa lebih efisien daripada menggunakan permintaan PUT karena klien hanya mengirim perubahan dan bukan seluruh representasi sumber daya. PATCH juga dapat membuat sumber daya baru dengan menentukan serangkaian pembaruan ke sumber daya kosong atau null jika server mendukung tindakan ini.

Dengan permintaan PATCH, klien mengirim serangkaian pembaruan ke sumber daya yang ada dalam bentuk dokumen patch. Server memproses dokumen patch untuk melakukan pembaruan. Dokumen patch hanya menentukan sekumpulan perubahan yang akan diterapkan alih-alih menjelaskan seluruh sumber daya. Spesifikasi untuk metode PATCH, RFC 5789, tidak menentukan format tertentu untuk dokumen patch. Format harus disimpulkan dari jenis media dalam permintaan.

JSON adalah salah satu format data paling umum untuk API web. Dua format patch utama berbasis JSON adalah patch JSON dan patch penggabungan JSON.

Patch penggabungan JSON lebih sederhana daripada patch JSON. Dokumen patch memiliki struktur yang sama dengan sumber daya JSON asli, tetapi hanya menyertakan subset bidang yang harus diubah atau ditambahkan. Selain itu, bidang dapat dihapus dengan menentukan null nilai bidang dalam dokumen patch. Spesifikasi ini berarti bahwa patch penggabungan tidak cocok jika sumber daya asli dapat memiliki nilai null eksplisit.

Misalnya, sumber daya asli memiliki representasi JSON berikut:

{
    "name":"gizmo",
    "category":"widgets",
    "color":"blue",
    "price":10
}

Berikut adalah kemungkinan patch penggabungan JSON untuk sumber daya ini:

{
    "price":12,
    "color":null,
    "size":"small"
}

Patch penggabungan ini memberi tahu server untuk memperbarui price, menghapus color, dan menambahkan size. Nilai untuk name dan category tidak dimodifikasi. Untuk informasi selengkapnya tentang patch penggabungan JSON, lihat RFC 7396. Jenis media untuk patch penggabungan JSON adalah application/merge-patch+json.

Patch penggabungan tidak cocok jika sumber daya asli dapat berisi nilai null yang eksplisit karena makna khusus dari null dalam dokumen patch. Dokumen patch juga tidak menentukan urutan server harus menerapkan pembaruan. Apakah pesanan ini penting tergantung pada data dan domain. Patch JSON, yang didefinisikan dalam RFC 6902, lebih fleksibel karena menentukan perubahan sebagai urutan operasi yang akan diterapkan, termasuk menambahkan, menghapus, mengganti, menyalin, dan menguji untuk memvalidasi nilai. Jenis media untuk patch JSON adalah application/json-patch+json.

Permintaan PATCH harus mengembalikan salah satu kode status HTTP berikut:

Kode Status HTTP Alasan
200 (OK) Sumber daya berhasil diperbarui.
400 (Permintaan Tidak Valid) Dokumen patch salah bentuk.
409 (Konflik) Dokumen patch valid, tetapi perubahan tidak dapat diterapkan ke sumber daya dalam statusnya saat ini.
415 (Tipe Media Yang Tidak Didukung) Format dokumen patch tidak didukung.

Permintaan DELETE

Permintaan DELETE menghapus sumber daya di URI yang ditentukan. Permintaan DELETE harus mengembalikan salah satu kode status HTTP berikut:

Kode Status HTTP Alasan
204 (TANPA KONTEN) Sumber daya berhasil dihapus. Proses telah berhasil ditangani dan isi respons tidak berisi informasi lebih lanjut.
404 (TIDAK DITEMUKAN) Sumber daya tidak ada.

Jenis MIME sumber daya

Representasi sumber daya adalah bagaimana sumber daya yang diidentifikasi oleh URI dikodekan dan diangkut melalui protokol HTTP dalam format tertentu, seperti XML atau JSON. Klien yang ingin mengambil sumber daya tertentu harus menggunakan URI dalam permintaan ke API. API merespons dengan mengembalikan representasi sumber daya dari data yang ditunjukkan oleh URI.

Dalam protokol HTTP, format representasi sumber daya ditentukan dengan menggunakan jenis media, juga disebut jenis MIME. Untuk data nonbiner, sebagian besar API web mendukung JSON (jenis media = application/json) dan mungkin XML (jenis media = application/xml).

Header Tipe Konten dalam permintaan atau respons menentukan format representasi sumber daya. Contoh berikut menunjukkan permintaan POST yang menyertakan data JSON:

POST https://api.contoso.com/orders
Content-Type: application/json; charset=utf-8
Content-Length: 57

{"Id":1,"Name":"Gizmo","Category":"Widgets","Price":1.99}

Jika server tidak mendukung jenis media, server harus mengembalikan kode status HTTP 415 (Jenis Media yang Tidak Didukung).

Permintaan klien dapat menyertakan header Terima yang berisi daftar jenis media yang diterima klien dari server dalam pesan respons. Contohnya:

GET https://api.contoso.com/orders/2
Accept: application/json, application/xml

Jika server tidak dapat mencocokkan salah satu jenis media yang tercantum, server harus mengembalikan kode status HTTP 406 (Tidak Dapat Diterima).

Menerapkan metode asinkron

Terkadang metode POST, PUT, PATCH, atau DELETE mungkin memerlukan pemrosesan yang membutuhkan waktu untuk diselesaikan. Jika Anda menunggu penyelesaian sebelum mengirim respons ke klien, itu dapat menyebabkan latensi yang tidak dapat diterima. Dalam skenario ini, pertimbangkan untuk membuat metode asinkron. Metode asinkron harus mengembalikan kode status HTTP 202 (Diterima) untuk menunjukkan bahwa permintaan diterima untuk diproses tetapi tidak lengkap.

Mengekspos endpoint yang mengembalikan status permintaan asinkron sehingga klien dapat memantau status melalui polling pada endpoint tersebut. Sertakan URI titik akhir status di header Lokasi respons 202. Contohnya:

HTTP/1.1 202 Accepted
Location: /api/status/12345

Jika klien mengirim permintaan GET ke titik akhir ini, respons harus berisi status permintaan saat ini. Secara opsional, ini dapat mencakup perkiraan waktu penyelesaian atau tautan untuk membatalkan operasi.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status":"In progress",
    "link": { "rel":"cancel", "method":"delete", "href":"/api/status/12345" }
}

Jika operasi asinkron membuat sumber daya baru, titik akhir status harus mengembalikan kode status 303 (Lihat Lainnya) setelah operasi selesai. Dalam respons 303, sertakan header Lokasi yang memberikan URI sumber daya baru:

HTTP/1.1 303 See Other
Location: /api/orders/12345

Untuk informasi selengkapnya, lihat Memberikan dukungan asinkron untuk permintaan yang berjalan lama dan pola Request-Reply Asinkron.

Menerapkan penomoran dan pemfilteran data

Untuk mengoptimalkan pengambilan data dan mengurangi ukuran payload, terapkan penomoran halaman data dan pemfilteran berbasis kueri dalam desain API Anda. Teknik ini memungkinkan klien untuk hanya meminta subset data yang mereka butuhkan, yang dapat meningkatkan performa dan mengurangi penggunaan bandwidth.

  • Penomoran halaman membagi himpunan data besar menjadi potongan yang lebih kecil dan dapat dikelola. Gunakan parameter kueri seperti limit untuk menentukan jumlah item yang akan dikembalikan dan offset untuk menentukan titik awal. Pastikan juga untuk memberikan default yang bermakna untuk limit dan offset, seperti limit=25 dan offset=0. Contohnya:

    GET /orders?limit=25&offset=50

    • limit: Menentukan jumlah maksimum item yang akan dikembalikan.

      Petunjuk / Saran

      Untuk membantu mencegah serangan penolakan layanan, pertimbangkan untuk memberlakukan batas atas jumlah item yang dikembalikan. Misalnya, jika layanan Anda menetapkan max-limit=25, dan klien meminta limit=1000, layanan Anda dapat mengembalikan 25 item atau kesalahan HTTP BAD-REQUEST, tergantung pada dokumentasi API.

    • offset: Menentukan indeks awal untuk data.

  • Pemfilteran memungkinkan klien untuk menyempurnakan himpunan data dengan menerapkan kondisi. API dapat memungkinkan klien untuk meneruskan filter dalam string kueri URI:

    GET /orders?minCost=100&status=shipped
    • minCost: Memfilter pesanan yang memiliki biaya minimum 100.
    • status: Memfilter pesanan yang memiliki status tertentu.

Pertimbangkan praktik terbaik berikut:

  • Pengurutan memungkinkan klien untuk mengurutkan data dengan menggunakan sort parameter seperti sort=price.

    Penting

    Pendekatan pengurutan dapat memiliki efek negatif pada penembolokan karena parameter dalam string kueri merupakan bagian dari identitas sumber daya yang digunakan banyak implementasi cache sebagai kunci untuk data yang di-cache.

  • Pemilihan bidang untuk proyeksi yang ditentukan klien memungkinkan klien untuk menentukan hanya bidang yang mereka butuhkan dengan menggunakan fields parameter seperti fields=id,name. Misalnya, Anda dapat menggunakan parameter string kueri yang menerima daftar bidang yang dibatasi koma, seperti /orders?fields=ProductID,Quantity.

API Anda harus memvalidasi bidang yang diminta untuk memastikan bahwa klien diizinkan untuk mengaksesnya dan tidak akan mengekspos bidang yang biasanya tidak tersedia melalui API.

Mendukung respons parsial

Beberapa sumber daya berisi bidang biner besar, seperti file atau gambar. Untuk mengatasi masalah yang disebabkan oleh koneksi yang tidak dapat diandalkan dan terputus-putus dan untuk meningkatkan waktu respons, pertimbangkan untuk mendukung pengambilan sebagian sumber daya biner besar.

Untuk mendukung respons parsial, API web harus mendukung header Accept-Ranges untuk permintaan GET untuk sumber daya besar. Header ini menunjukkan bahwa operasi GET mendukung permintaan parsial. Aplikasi klien dapat mengirimkan permintaan GET yang mengembalikan subset sumber daya, yang ditentukan sebagai rentang byte.

Selain itu, pertimbangkan untuk menerapkan permintaan HTTP HEAD untuk sumber daya ini. Permintaan HEAD mirip dengan permintaan GET, kecuali hanya mengembalikan header HTTP yang menjelaskan sumber daya, dengan isi pesan kosong. Aplikasi klien dapat mengeluarkan permintaan HEAD untuk menentukan apakah akan mengambil sumber daya dengan menggunakan permintaan GET parsial. Contohnya:

HEAD https://api.contoso.com/products/10?fields=productImage

Berikut adalah contoh pesan respons:

HTTP/1.1 200 OK

Accept-Ranges: bytes
Content-Type: image/jpeg
Content-Length: 4580

Header Content-Length memberikan ukuran total sumber daya, dan header Accept-Ranges menunjukkan bahwa operasi GET yang sesuai mendukung hasil parsial. Aplikasi klien dapat menggunakan informasi ini untuk mengambil gambar dalam gugus yang lebih kecil. Permintaan pertama mengambil 2.500 byte pertama dengan menggunakan header Range:

GET https://api.contoso.com/products/10?fields=productImage
Range: bytes=0-2499

Pesan respons menunjukkan bahwa respons ini parsial dengan mengembalikan kode status HTTP 206. Header Content-Length menentukan jumlah byte aktual yang dikembalikan dalam isi pesan dan bukan ukuran sumber daya. Header Rentang Konten menunjukkan bagian sumber daya mana yang dikembalikan (byte 0-2499 dari 4580):

HTTP/1.1 206 Partial Content

Accept-Ranges: bytes
Content-Type: image/jpeg
Content-Length: 2500
Content-Range: bytes 0-2499/4580

[...]

Permintaan berikutnya dari aplikasi klien dapat mengambil sisa sumber daya.

Menerapkan HATEOAS

Salah satu alasan utama untuk menggunakan REST adalah kemampuan untuk menavigasi seluruh set sumber daya tanpa pengetahuan sebelumnya tentang skema URI. Setiap permintaan HTTP GET harus mengembalikan informasi yang diperlukan untuk menemukan sumber daya yang terkait langsung dengan objek yang diminta melalui hyperlink yang disertakan dalam respons. Permintaan juga harus diberikan informasi yang menjelaskan operasi yang tersedia pada masing-masing sumber daya ini. Prinsip ini dikenal sebagai HATEOAS, atau Hypertext sebagai Engine of Application State. Sistem ini secara efektif merupakan mesin status terbatas, dan respons terhadap setiap permintaan berisi informasi yang diperlukan untuk berpindah dari satu status ke status lainnya. Tidak ada informasi lain yang diperlukan.

Nota

Tidak ada standar tujuan umum yang menentukan cara memodelkan prinsip HATEOAS. Contoh di bagian ini menggambarkan satu kemungkinan solusi eksklusif.

Misalnya, untuk menangani hubungan antara pesanan dan pelanggan, representasi pesanan mungkin menyertakan tautan yang mengidentifikasi operasi yang tersedia untuk pelanggan pesanan. Blok kode berikut adalah representasi yang mungkin:

{
  "orderID":3,
  "productID":2,
  "quantity":4,
  "orderValue":16.60,
  "links":[
    {
      "rel":"customer",
      "href":"https://api.contoso.com/customers/3",
      "action":"GET",
      "types":["text/xml","application/json"]
    },
    {
      "rel":"customer",
      "href":"https://api.contoso.com/customers/3",
      "action":"PUT",
      "types":["application/x-www-form-urlencoded"]
    },
    {
      "rel":"customer",
      "href":"https://api.contoso.com/customers/3",
      "action":"DELETE",
      "types":[]
    },
    {
      "rel":"self",
      "href":"https://api.contoso.com/orders/3",
      "action":"GET",
      "types":["text/xml","application/json"]
    },
    {
      "rel":"self",
      "href":"https://api.contoso.com/orders/3",
      "action":"PUT",
      "types":["application/x-www-form-urlencoded"]
    },
    {
      "rel":"self",
      "href":"https://api.contoso.com/orders/3",
      "action":"DELETE",
      "types":[]
    }]
}

Dalam contoh ini, links array memiliki sekumpulan tautan. Setiap tautan mewakili operasi pada entitas terkait. Data untuk setiap tautan mencakup hubungan ("pelanggan"), URI (https://api.contoso.com/customers/3), metode HTTP, dan jenis MIME yang didukung. Aplikasi klien memerlukan informasi ini untuk memanggil operasi.

Array links juga menyertakan informasi referensi mandiri tentang sumber daya yang diambil. Tautan ini memiliki hubungan diri sendiri.

Kumpulan tautan yang dikembalikan dapat berubah tergantung pada status sumber daya. Gagasan bahwa hypertext adalah mesin status aplikasi menjelaskan skenario ini.

Menerapkan versi

API web tidak tetap statis. Saat persyaratan bisnis berubah, koleksi sumber daya baru ditambahkan. Saat sumber daya baru ditambahkan, hubungan antara sumber daya mungkin berubah, dan struktur data dalam sumber daya mungkin diubah. Memperbarui API web untuk menangani persyaratan baru atau berbeda adalah proses yang mudah, tetapi Anda harus mempertimbangkan efek yang dimiliki perubahan tersebut pada aplikasi klien yang menggunakan API web. Pengembang yang merancang dan mengimplementasikan API web memiliki kontrol penuh atas API tersebut, tetapi mereka tidak memiliki tingkat kontrol yang sama atas aplikasi klien yang dibangun oleh organisasi mitra. Penting untuk terus mendukung aplikasi klien yang ada sambil memungkinkan aplikasi klien baru menggunakan fitur dan sumber daya baru.

API web yang menerapkan penerapan versi dapat menunjukkan fitur dan sumber daya yang dieksposnya, dan aplikasi klien dapat mengirimkan permintaan yang diarahkan ke versi tertentu dari fitur atau sumber daya. Bagian berikut menjelaskan beberapa pendekatan yang berbeda, yang masing-masing memiliki manfaat dan trade-off sendiri.

Tidak ada penerapan versi

Pendekatan ini adalah yang paling sederhana dan dapat berfungsi untuk beberapa API internal. Perubahan signifikan dapat direpresentasikan sebagai sumber daya baru atau tautan baru. Menambahkan konten ke sumber daya yang sudah ada mungkin tidak menyebabkan perubahan yang merusak kompatibilitas karena aplikasi klien yang tidak mengharapkan konten ini akan mengabaikannya.

Misalnya, permintaan ke URI https://api.contoso.com/customers/3 harus mengembalikan detail satu pelanggan yang berisi bidang id, name, dan address yang diharapkan aplikasi klien:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Fabrikam, Inc.","address":"1 Microsoft Way Redmond WA 98053"}

Nota

Untuk kesederhanaan, contoh respons yang ditampilkan di bagian ini tidak menyertakan tautan HATEOAS.

DateCreated Jika bidang ditambahkan ke skema sumber daya pelanggan, responsnya terlihat seperti:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Fabrikam, Inc.","dateCreated":"2025-03-22T12:11:38.0376089Z","address":"1 Microsoft Way Redmond WA 98053"}

Aplikasi klien yang ada mungkin terus berfungsi dengan benar jika mereka dapat mengabaikan bidang yang tidak dikenal. Sementara itu, aplikasi klien baru dapat dirancang untuk menangani bidang baru ini. Namun, modifikasi yang lebih drastis pada skema sumber daya, termasuk penghapusan bidang atau penggantian nama, dapat terjadi. Atau hubungan antara sumber daya mungkin berubah. Pembaruan ini dapat merupakan perubahan signifikan yang dapat mengganggu aplikasi klien yang ada agar tidak berfungsi dengan benar. Dalam skenario ini, pertimbangkan salah satu pendekatan berikut:

Pengelolaan versi URI

Setiap kali Anda mengubah API web atau mengubah skema sumber daya, Anda menambahkan nomor versi ke URI untuk setiap sumber daya. URI yang ada sebelumnya harus terus beroperasi secara normal dengan mengembalikan sumber daya yang sesuai dengan skema aslinya.

Misalnya, address bidang dalam contoh sebelumnya direstrukturisasi menjadi subbidang yang berisi setiap bagian konstituen dari alamat, seperti streetAddress, city, state, dan zipCode. Versi sumber daya ini dapat diekspos melalui URI yang berisi nomor versi, seperti https://api.contoso.com/v2/customers/3:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Fabrikam, Inc.","dateCreated":"2025-03-22T12:11:38.0376089Z","address":{"streetAddress":"1 Microsoft Way","city":"Redmond","state":"WA","zipCode":98053}}

Mekanisme penerapan versi ini sederhana tetapi tergantung pada server untuk merutekan permintaan ke titik akhir yang sesuai. Namun, bisa menjadi sulit diatur saat API web matang dengan beberapa iterasi dan server harus mendukung berbagai versi berbeda. Dari sudut pandang idealis, dalam setiap keadaan, aplikasi klien mengambil data yang sama (pelanggan ketiga), sehingga URI seharusnya tidak berbeda berdasarkan versi. Skema ini juga mempersulit implementasi HATEOAS karena semua tautan perlu menyertakan nomor versi dalam URI mereka.

Penerapan versi string kueri

Alih-alih menyediakan beberapa URI, Anda dapat menentukan versi sumber daya dengan menggunakan parameter dalam string kueri yang ditambahkan ke permintaan HTTP, seperti https://api.contoso.com/customers/3?version=2. Parameter versi harus default ke nilai yang bermakna, seperti 1, jika aplikasi klien yang lebih lama menghilangkannya.

Pendekatan ini memiliki keuntungan semantik bahwa sumber daya yang sama selalu diambil dari URI yang sama. Namun, metode ini tergantung pada kode yang menangani permintaan untuk mengurai string kueri dan mengirim kembali respons HTTP yang sesuai. Pendekatan ini juga mempersulit implementasi HATEOAS dengan cara yang sama seperti mekanisme penerapan versi URI.

Nota

Beberapa browser web dan proksi web yang lebih lama tidak menyimpan respons untuk permintaan yang menyertakan string kueri dalam URI. Respons yang tidak di-cache dapat menurunkan performa untuk aplikasi web yang menggunakan API web dan berjalan dari dalam browser web yang lebih lama.

Penerapan versi header

Alih-alih menambahkan nomor versi sebagai parameter string kueri, Anda dapat menerapkan header kustom yang menunjukkan versi sumber daya. Pendekatan ini mengharuskan aplikasi klien menambahkan header yang sesuai ke permintaan apa pun. Namun, kode yang menangani permintaan klien dapat menggunakan nilai default, seperti versi 1, jika header versi dihilangkan.

Contoh berikut menggunakan header kustom bernama Custom-Header. Nilai header ini menunjukkan versi API web.

Versi 1:

GET https://api.contoso.com/customers/3
Custom-Header: api-version=1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Fabrikam, Inc.","address":"1 Microsoft Way Redmond WA 98053"}

Versi 2:

GET https://api.contoso.com/customers/3
Custom-Header: api-version=2

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Fabrikam, Inc.","dateCreated":"2025-03-22T12:11:38.0376089Z","address":{"streetAddress":"1 Microsoft Way","city":"Redmond","state":"WA","zipCode":98053}}

Mirip dengan penerapan versi URI dan penerapan versi string kueri, Anda harus menyertakan header kustom yang sesuai dalam tautan apa pun untuk mengimplementasikan HATEOAS.

Versi jenis media

Saat aplikasi klien mengirim permintaan HTTP GET ke server web, aplikasi harus menggunakan header Terima untuk menentukan format konten yang dapat ditanganinya. Biasanya, tujuan header Terima adalah untuk memungkinkan aplikasi klien menentukan apakah isi respons harus XML, JSON, atau beberapa format umum lainnya yang dapat diurai klien. Namun, dimungkinkan untuk menentukan jenis media kustom yang menyertakan informasi yang memungkinkan aplikasi klien menunjukkan versi sumber daya mana yang diharapkan.

Contoh berikut menunjukkan permintaan yang menentukan header Terima dengan nilai application/vnd.contoso.v1+json. Elemen vnd.contoso.v1 menunjukkan ke server web bahwa elemen tersebut harus mengembalikan sumber daya versi 1. Elemen json menentukan bahwa format isi respons harus JSON:

GET https://api.contoso.com/customers/3
Accept: application/vnd.contoso.v1+json

Kode yang menangani permintaan bertanggung jawab untuk memproses header Terima dan menghormatinya sebanyak mungkin. Aplikasi klien dapat menentukan beberapa format di header Terima, yang memungkinkan server web memilih format yang paling sesuai untuk isi respons. Server web mengonfirmasi format data dalam isi respons dengan menggunakan header Tipe Konten:

HTTP/1.1 200 OK
Content-Type: application/vnd.contoso.v1+json; charset=utf-8

{"id":3,"name":"Fabrikam, Inc.","address":"1 Microsoft Way Redmond WA 98053"}

Jika header Terima tidak menentukan jenis media yang diketahui, server web dapat menghasilkan pesan respons HTTP 406 (Tidak Dapat Diterima) atau mengembalikan pesan dengan jenis media default.

Mekanisme penerapan versi ini mudah dan cocok untuk HATEOAS, yang dapat menyertakan jenis MIME data terkait dalam tautan sumber daya.

Nota

Saat Anda memilih strategi versioning, ada implikasi, khususnya terkait dengan penembolokan server web. Skema penerapan versi URI dan penerapan versi string kueri ramah cache karena kombinasi URI atau string kueri yang sama mengacu pada data yang sama setiap kali.

Mekanisme penerapan versi header dan penerapan versi jenis media biasanya memerlukan lebih banyak logika untuk memeriksa nilai di header kustom atau header Terima. Dalam lingkungan skala besar, banyak klien yang menggunakan versi API web yang berbeda dapat menghasilkan sejumlah besar data duplikat dalam cache sisi server. Masalah ini dapat menjadi parah jika aplikasi klien berkomunikasi dengan server web melalui proksi yang menerapkan caching dan hanya meneruskan permintaan ke server web jika saat ini tidak memiliki salinan data yang diminta dalam cache-nya.

API web multipenyewa

Solusi API web multitenant dibagikan dengan beberapa penyewa, seperti organisasi yang berbeda-beda yang memiliki grup pengguna mereka sendiri.

Multitenancy secara signifikan memengaruhi desain API web karena menentukan bagaimana sumber daya diakses dan ditemukan di beberapa penyewa dalam satu API web. Desain API dengan mempertimbangkan multitenansi untuk membantu menghindari kebutuhan refaktor di masa mendatang untuk menerapkan isolasi, skalabilitas, atau kustomisasi khusus penyewa.

API yang dirancang dengan baik harus dengan jelas menentukan bagaimana penyewa diidentifikasi dalam permintaan, baik melalui subdomain, jalur, header, atau token. Struktur ini memastikan pengalaman yang konsisten namun fleksibel untuk semua pengguna dalam sistem. Untuk informasi selengkapnya, lihat Pemetaan permintaan ke penyewa dalam solusi multipenyewa.

Multitenancy memengaruhi struktur titik akhir, penanganan permintaan, autentikasi, dan otorisasi. Pendekatan ini juga memengaruhi bagaimana gateway API, load balancer, dan layanan back-end merutekan dan memproses permintaan. Strategi berikut adalah cara umum untuk mencapai multitenansi dalam API web.

Menggunakan subdomain atau isolasi berbasis domain (penyewaan tingkat DNS)

Pendekatan ini merutekan permintaan dengan menggunakan domain khusus penyewa. Domain wildcard menggunakan subdomain untuk fleksibilitas dan kesederhanaan. Domain kustom, yang memungkinkan penyewa menggunakan domain mereka sendiri, memberikan kontrol yang lebih besar dan dapat disesuaikan untuk memenuhi kebutuhan tertentu. Kedua metode mengandalkan konfigurasi DNS yang tepat, termasuk A dan CNAME rekaman, untuk mengarahkan lalu lintas ke infrastruktur yang sesuai. Domain wildcard menyederhanakan konfigurasi, tetapi domain kustom memberikan pengalaman yang lebih bermerk.

Pertahankan hostname antara reverse proxy dan layanan belakang untuk menghindari masalah seperti pengalihan URL dan mencegah tereksposnya URL internal. Metode ini memastikan perutean lalu lintas khusus penyewa yang benar dan membantu melindungi infrastruktur internal. Resolusi DNS sangat penting untuk mencapai residensi data dan memastikan kepatuhan terhadap peraturan.

GET https://adventureworks.api.contoso.com/orders/3

Teruskan header HTTP khusus penyewa

Informasi penyewa dapat diteruskan melalui header HTTP kustom seperti X-Tenant-ID atau X-Organization-ID melalui header berbasis host seperti Host atau X-Forwarded-Host, atau dapat diekstrak dari klaim JSON Web Token (JWT). Pilihannya tergantung pada kemampuan perutean gateway API atau proksi terbalik Anda, dengan solusi berbasis header yang memerlukan gateway Layer 7 (L7) untuk memeriksa setiap permintaan. Persyaratan ini menambahkan beban pemrosesan, yang meningkatkan biaya komputasi ketika volume lalu lintas meningkat. Namun, isolasi berbasis header memberikan manfaat utama. Ini memungkinkan autentikasi terpusat, yang menyederhanakan manajemen keamanan di seluruh API multipenyewa. Dengan menggunakan klien SDK atau API, konteks penyewa dikelola secara dinamis pada runtime, yang mengurangi kompleksitas konfigurasi sisi klien. Selain itu, menjaga konteks penyewa dalam header menghasilkan desain API yang lebih bersih dan lebih RESTful dengan menghindari data khusus penyewa di URI.

Pertimbangan penting untuk perutean berbasis header adalah bahwa itu mempersulit penyimpanan cache, terutama ketika lapisan cache hanya mengandalkan kunci berbasis URI dan tidak memperhitungkan header. Karena sebagian besar mekanisme penembolokan mengoptimalkan pencarian URI, mengandalkan header dapat menyebabkan entri cache terfragmentasi. Entri terfragmentasi mengurangi hit cache dan meningkatkan beban back-end. Yang lebih berisiko, jika lapisan penembolokan tidak membedakan respons berdasarkan tajuk, lapisan tersebut dapat menyajikan data cache yang ditujukan untuk satu penyewa ke penyewa lainnya dan menyebabkan risiko kebocoran data.

GET https://api.contoso.com/orders/3
X-Tenant-ID: adventureworks

atau

GET https://api.contoso.com/orders/3
Host: adventureworks

atau

GET https://api.contoso.com/orders/3
Authorization: Bearer <JWT-token including a tenant-id: adventureworks claim>

Meneruskan informasi khusus penyewa melalui jalur URI

Pendekatan ini menambahkan pengidentifikasi penyewa dalam hierarki sumber daya dan bergantung pada gateway API atau proksi terbalik untuk menentukan penyewa yang sesuai berdasarkan segmen jalur. Isolasi berbasis jalur memang efektif, namun dapat mengkompromikan desain RESTful pada API web dan memperkenalkan logika perutean yang lebih kompleks. Ini sering membutuhkan pencocokan pola atau ekspresi reguler untuk mengurai dan menganonisasi jalur URI.

Sebaliknya, isolasi yang berbasis header menyampaikan informasi penyewa melalui header HTTP dalam bentuk pasangan kunci-nilai. Kedua pendekatan memungkinkan berbagi infrastruktur yang efisien untuk menurunkan biaya operasional dan meningkatkan performa dalam API web multipenyewa berskala besar.

GET https://api.contoso.com/tenants/adventureworks/orders/3

Mengaktifkan pelacakan terdistribusi dan konteks pelacakan di API

Karena sistem terdistribusi dan arsitektur layanan mikro menjadi standar, kompleksitas arsitektur modern meningkat. Menggunakan header, seperti Correlation-ID, , X-Request-IDatau X-Trace-ID, untuk menyebarluaskan konteks pelacakan dalam permintaan API adalah praktik terbaik untuk mencapai visibilitas end-to-end. Pendekatan ini memungkinkan pelacakan permintaan yang mulus saat mengalir dari klien ke layanan back-end. Ini memfasilitasi identifikasi kegagalan yang cepat, memantau latensi, dan memetakan dependensi API di seluruh layanan.

API yang mendukung penyertaan informasi jejak dan konteks meningkatkan tingkat pengamatan dan kemampuan penelusuran kesalahan mereka. Dengan mengaktifkan pelacakan terdistribusi, API ini memungkinkan pemahaman perilaku sistem yang lebih terperinci dan memudahkan untuk melacak, mendiagnosis, dan menyelesaikan masalah di seluruh lingkungan beberapa layanan yang kompleks.

GET https://api.contoso.com/orders/3
Correlation-ID: 0f8fad5b-d9cb-469f-a165-70867728950e

HTTP/1.1 200 OK
...
Correlation-ID: 0f8fad5b-d9cb-469f-a165-70867728950e

{...}

Model kematangan API Web

Pada tahun 2008, Leonard Richardson mengusulkan apa yang sekarang dikenal sebagai Richardson Maturity Model (RMM) untuk API web. RMM mendefinisikan empat tingkat kematangan untuk API web dan didasarkan pada prinsip REST sebagai pendekatan arsitektur untuk merancang layanan web. Dalam RMM, ketika tingkat kematangan meningkat, API menjadi lebih RESTful dan lebih erat mengikuti prinsip REST.

Tingkatnya adalah:

  • Tingkat 0: Tentukan satu URI, dan semua operasi adalah permintaan POST ke URI ini. Layanan web Protokol Akses Objek Sederhana biasanya pada tingkat ini.
  • Tingkat 1: Buat URI terpisah untuk sumber daya individual. Tingkat ini belum RESTful, tetapi mulai selaras dengan desain RESTful.
  • Tingkat 2: Gunakan metode HTTP untuk menentukan operasi pada sumber daya. Dalam praktiknya, banyak API web yang diterbitkan selaras kira-kira dengan tingkat ini.
  • Tingkat 3: Gunakan hypermedia (HATEOAS). Tingkat ini benar-benar API RESTful, menurut definisi Fielding.

Inisiatif OpenAPI

Inisiatif OpenAPI dibuat oleh konsorsium industri untuk menstandarkan deskripsi REST API di seluruh vendor. Spesifikasi standardisasi disebut Swagger sebelum dibawa di bawah Inisiatif OpenAPI dan diganti namanya menjadi Spesifikasi OpenAPI (OAS).

Anda mungkin ingin mengadopsi OpenAPI untuk API web RESTful Anda. Pertimbangkan poin-poin berikut:

  • OAS dilengkapi dengan serangkaian pedoman berpendapat untuk desain REST API. Panduan ini menguntungkan untuk interoperabilitas tetapi mengharuskan Anda memastikan bahwa desain Anda sesuai dengan spesifikasi.

  • OpenAPI mempromosikan pendekatan kontrak-pertama alih-alih pendekatan implementasi-pertama. Kontrak-pertama berarti Anda merancang kontrak API (antarmuka) terlebih dahulu dan kemudian menulis kode yang mengimplementasikan kontrak.

  • Alat seperti Swagger (OpenAPI) dapat menghasilkan pustaka klien atau dokumentasi dari kontrak API. Misalnya, lihat dokumentasi API web ASP.NET Core dengan Swagger/OpenAPI.

Langkah berikutnya