Memahami dan Menggunakan RESTful API

Di era Internet of Everything, terdapat banyak API yang berbeda, dan penting untuk menstandarisasikannya. RESTful API adalah salah satu gaya arsitektur API yang paling populer, yang dapat membantu Anda memisahkan perhatian sisi klien dan server, memungkinkan front-end dan back-end untuk beriterasi secara terpisah sehingga meningkatkan efisiensi. Fitur stateless-nya dapat membuat aplikasi lebih skalabel dan lebih mudah untuk menerapkan kebijakan caching guna meningkatkan pengalaman pengguna dan kinerja. Dalam artikel ini, kami akan memperkenalkan apa itu RESTful API dan bagaimana kita dapat menggunakannya.

Apa Itu API

Mengabaikan sejenak apa itu API, mari kita bicara tentang bagaimana kita menyampaikan informasi dalam kehidupan sehari-hari.

Ketika Anda membawa uang Anda ke pemilik toko dan mengatakan kepadanya bahwa Anda perlu membeli baterai, pemilik toko menerima uang tersebut, menemukan baterai di rak, dan menyerahkannya kepada Anda. Transaksi untuk membeli baterai berhasil diselesaikan.

Di sisi lain, perangkat lunak komputer menyelesaikan ini melalui API. Mari kita mulai dengan definisi dari Wikipedia:

Antarmuka pemrograman aplikasi (API) adalah cara bagi dua atau lebih program komputer untuk berkomunikasi satu sama lain. Ini adalah jenis antarmuka perangkat lunak, yang menawarkan layanan ke bagian perangkat lunak lainnya.

Perangkat lunak A membuat permintaan ke Perangkat lunak B melalui API, dan Perangkat lunak B mengembalikan respons ke A melalui API setelah menanyakan sumber dayanya.

Perangkat lunak A membuat permintaan ke Perangkat lunak B melalui API seperti Anda memberi tahu bos Anda bahwa Anda membutuhkan baterai, dan Perangkat lunak B mengembalikan data ke Perangkat lunak A seperti bos Anda menemukan baterai dan memberikannya kepada Anda.

Proses ini tidak mengharuskan Perangkat lunak B untuk mengetahui mengapa Perangkat lunak A menginginkan data, sama seperti pemilik toko tidak akan bertanya mengapa Anda membeli baterai. Perangkat lunak A juga tidak perlu tahu bagaimana perangkat lunak B menemukan data, sama seperti Anda tidak akan bertanya kepada pemilik toko dari mana baterai tersebut dibeli ketika Anda membelinya. Setiap perangkat lunak saling menyampaikan informasi melalui API, dan masing-masing melakukan tugasnya sendiri, membuat dunia pemrograman menjadi teratur dan dapat diandalkan.

Apa Itu RESTful API

Roy Fielding mendefinisikan REST (Representational state transfer) dalam disertasi Ph.D. tahun 2000, "Architectural Styles and Web-Based Software Architecture Design," dan gaya arsitektur REST mendefinisikan enam batasan panduan. Sistem yang sesuai dengan beberapa atau semua batasan ini secara longgar disebut sebagai RESTful.

(Sumber: Seobility)

Batasan RESTful API

Praktik Terbaik RESTful API

Penekanan pada antarmuka seragam antara komponen adalah fitur inti yang membedakan gaya arsitektur REST dari gaya berbasis web lainnya, dan berdasarkan fitur ini, praktik terbaik disusun di sini untuk membantu Anda merancang API dengan lebih baik.

Hindari Kata Kerja dalam Nama Path

Gunakan metode HTTP untuk mengekspresikan perilaku manipulasi sumber daya, alih-alih mendefinisikan kata kerja perilaku ke dalam path.

// Baik
curl -X GET http://httpbin.org/orders

// Buruk
curl -X GET "http://httpbin.org/getOrders"

• Dapatkan informasi sumber daya untuk URI yang ditentukan menggunakan GET

// Mewakili mendapatkan semua informasi pesanan untuk sistem saat ini
curl -X GET http://httpbin.org/orders

// Mewakili mendapatkan informasi detail pesanan untuk nomor pesanan 1
curl -X GET http://httpbin.org/orders/1

• Buat sumber daya dari URI yang ditentukan menggunakan POST

 // Mewakili pembuatan sumber daya dengan nama pesanan
curl -X POST http://httpbin.org/orders \
  -d '{"name": "awesome", region: "A"}' \

• Buat atau ganti sepenuhnya sumber daya pada URI yang ditentukan menggunakan PUT

 // Mewakili penggantian data untuk pesanan dengan id 1
curl -X PUT http://httpbin.org/orders/1 \
  -d '{"name": "new awesome", region: "B"}' \

• PATCH melakukan pembaruan sebagian dari sumber daya

 // Mewakili mengubah bidang region dari pesanan dengan id 1, sambil menjaga data lainnya tetap tidak berubah
curl -X PATCH http://httpbin.org/orders/1 \
  -d '{region: "B"}' \

• Hapus sumber daya dengan menentukan URI menggunakan DELETE

 // Mewakili penghapusan pesanan dengan id 1
curl -X DELETE http://httpbin.org/orders/1

URI Menggunakan Bentuk Jamak

Jika Anda ingin menggunakan bentuk tunggal untuk menunjukkan akses ke jenis sumber daya tertentu:

curl -X GET "http://httpbin.org/order"

Menggunakan bentuk tunggal akan membingungkan pengguna bahwa hanya ada satu pesanan dalam sistem, tetapi menggunakan bentuk jamak akan membuatnya lebih mudah dipahami.

curl -X GET "http://httpbin.org/orders"

Memanfaatkan Kode Status HTTP dengan Baik

Standar HTTP mendefinisikan kode status, yang dapat diklasifikasikan secara luas ke dalam kategori berikut:

Dengan menggunakan kode status standar, pengembang dapat segera mengidentifikasi masalah dan dapat mengurangi waktu yang dibutuhkan untuk menemukan berbagai jenis kesalahan.

Kontrol Versi

Seiring perubahan kebutuhan bisnis, API yang sudah online kemungkinan besar harus disesuaikan. Jika API kami digunakan oleh pihak ketiga, jelas tidak mungkin untuk meminta setiap klien berubah sesuai dengan perubahan API kami, jadi inilah saatnya untuk memperkenalkan konsep manajemen versi API, yang dapat memastikan penggunaan normal API historis dan mengiterasi API baru untuk memenuhi kebutuhan bisnis baru.

Cara umum untuk kontrol versi adalah:

• Kontrol Versi melalui Path dalam Permintaan

// Permintaan API v1
curl  http://httpbin.org/v1/orders

// Permintaan API v2
curl  http://httpbin.org/v2/orders

• Kontrol Versi melalui Parameter Query

// Permintaan API v1
curl  http://httpbin.org/orders?version=v1

// Permintaan API v2
curl  http://httpbin.org/v2/orders?version=v2

• Kontrol Versi melalui Header

// Permintaan API v1
curl  http://httpbin.org/orders -H "custom-version: v1"

// Permintaan API v2
curl  http://httpbin.org/orders -H "custom-version: v2"

Bagaimana APISIX Memberdayakan RESTful API

Apache APISIX adalah gateway API yang dinamis, real-time, dan berkinerja tinggi. Ini dapat berjalan di depan layanan RESTful API apa pun dan menggunakan plugin untuk menambahkan layanan baru dan memperluas fungsinya, yang sesuai dengan definisi RESTful tentang Sistem Berlapis. Selain itu, untuk beberapa layanan historis yang tidak mengikuti definisi RESTful API, APISIX juga dapat membantu Anda mengonversi antarmuka Anda tanpa mengubah kode bisnis asli sehingga antarmuka Anda memenuhi batasan REST tentang Antarmuka Seragam, membuat API Anda lebih sesuai dengan spesifikasi RESTful API.

Sistem Berlapis: Mendukung Pemisahan Logika Bisnis dan Logika Keamanan

Anda dapat fokus pada implementasi logika bisnis, logika keamanan antarmuka dapat diserahkan ke plugin Autentikasi APISIX, misalnya key-auth. APISIX mendukung banyak plugin Autentikasi, mari kita ambil contoh openid-connect, seperti yang ditunjukkan pada gambar berikut:

Kita dapat melihat bahwa menggunakan APISIX (API Gateway) untuk menambahkan lapisan logika autentikasi di depan server bisnis kami dapat melindungi layanan upstream, dan pola arsitektur ini dapat menjadi cara yang baik untuk memisahkan logika bisnis Anda dari logika keamanan.

Sistem Berlapis: Dukungan Multi-Protokol Load Balancing

APISIX, sebagai gateway API, dapat diatur antara sisi klien dan server untuk memenuhi kebutuhan load balancing yang berbeda. Anda bahkan dapat menyesuaikan logika load balancing.

Algoritma load balancing yang didukung adalah:

• roundrobin: Round robin balancing dengan bobot.
• chash: Hash konsisten.
• ewma: Memilih node dengan latensi minimum. Lihat EWMA Chart untuk detail lebih lanjut.
• least_conn: Memilih node dengan nilai terendah dari (active_conn + 1) / weight. Di sini, koneksi aktif adalah koneksi yang digunakan oleh permintaan dan mirip dengan konsep di Nginx.
• Load balancer yang ditentukan pengguna dimuat melalui require("apisix.balancer.your_balancer")

Antarmuka Seragam: Membuat API Historis Lebih RESTful

Untuk API historis yang sudah lama ada dan tidak mengikuti panduan RESTful API dengan baik, Anda dapat mengemas ulang API baru melalui APISIX untuk memenuhi berbagai skenario bisnis tanpa mengubah logika API asli.

• Gunakan proxy-rewrite untuk menulis ulang permintaan klien

Seperti disebutkan di atas, kita seharusnya tidak memiliki kata kerja dalam path kita.

Misalnya, jika API historis memiliki antarmuka /getOrder, kita dapat memproksi permintaan API ke API historis melalui plugin proxy-rewrite.

curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "methods": ["GET"],
    "uri": "/orders",
    "plugins": {
        "proxy-rewrite": {
            "uri": "/getOrder",
            "scheme": "http",
        }
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:80": 1
        }
    }
}'

Anda juga dapat menggunakan plugin untuk operasi versioning API.

• Gunakan plugin response-rewrite untuk menulis ulang respons server

Ketika API historis kami memiliki kode status respons yang tidak standar, kita dapat menggunakan response-rewrite untuk memproksi respons untuk mengubah kode status respons.

curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "methods": ["GET"],
    "uri": "/orders",
    "plugins": {
        "response-rewrite": {
            "status_code": 201,
            "body": "{\"code\":\"ok\",\"message\":\"new json body\"}",
            "vars":[
                [ "status","==",200 ]
            ]
        }
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:80": 1
        }
    }
}'

Contoh di atas mewakili permintaan untuk mengubah status 200 menjadi 201 dalam API yang meminta path /orders.

Karena APISIX mendukung plugin yang sangat kaya, saya menantikan Anda untuk menjelajahi lebih banyak cara bermain.

Ringkasan

Artikel ini memperkenalkan apa itu API, apa itu RESTful API, dan praktik terbaiknya. Selain itu, artikel ini juga memperkenalkan bagaimana memisahkan logika bisnis dan logika keamanan melalui APISIX, dan bagaimana menggunakan APISIX untuk membuat layanan API historis lebih RESTful tanpa mengubah kode bisnis asli. Semoga artikel ini membantu Anda memahami RESTful API.