Halaman ini berlaku untuk Apigee dan Apigee Hybrid.
Baca dokumentasi Apigee Edge.
Dokumen ini memberikan serangkaian praktik terbaik untuk mengembangkan proxy API dengan Apigee.
Topik yang dibahas di sini mencakup desain, coding, penggunaan kebijakan, pemantauan, dan proses debug. Informasi ini dikumpulkan berdasarkan pengalaman developer yang menggunakan Apigee untuk mengimplementasikan program API yang sukses. Dokumen ini akan terus diperbarui dan akan diperbarui dari waktu ke waktu.
Selain panduan di sini, Anda mungkin juga merasa Pengantar antipola bermanfaat.
Standar pengembangan
Komentar dan Dokumentasi
- Memberikan komentar inline dalam konfigurasi
ProxyEndpoint
danTargetEndpoint
. Komentar meningkatkan keterbacaan untuk Flow, terutama jika nama file kebijakan tidak cukup deskriptif untuk mengekspresikan fungsi yang mendasarinya. - Buatlah komentar yang berguna. Hindari komentar yang tidak jelas.
- Gunakan indentasi, spasi, perataan vertikal yang konsisten, dan sebagainya.
Coding bergaya framework
Coding gaya framework melibatkan penyimpanan resource proxy API dalam sistem kontrol versi Anda sendiri untuk digunakan kembali di seluruh lingkungan pengembangan lokal. Misalnya, untuk menggunakan kembali kebijakan, simpan kebijakan tersebut di kontrol sumber agar developer dapat menyinkronkannya dan menggunakannya di lingkungan pengembangan proxy mereka sendiri.
- Untuk mengaktifkan DRY (jangan ulangi sendiri), jika memungkinkan, konfigurasi kebijakan dan skrip harus mengimplementasikan fungsi khusus yang dapat digunakan kembali. Misalnya, kebijakan khusus untuk mengekstrak parameter kueri dari pesan permintaan dapat disebut
ExtractVariables.ExtractRequestParameters
. - Bersihkan kebijakan dan resource yang tidak digunakan (JavaScript, Java, XSLT, ) dari proxy API, terutama resource besar yang berpotensi memperlambat prosedur impor dan deployment.
Konvensi Penamaan
- Atribut
name
kebijakan dan nama file kebijakan XML harus sama. - Atribut
name
kebijakan Skrip dan ServiceCallout serta nama file resource harus sama. DisplayName
harus menjelaskan fungsi kebijakan secara akurat kepada seseorang yang belum pernah menggunakan proxy API tersebut sebelumnya.- Beri nama kebijakan sesuai dengan fungsinya. Apigee merekomendasikan agar Anda menetapkan konvensi penamaan yang konsisten untuk kebijakan Anda.
Misalnya, gunakan awalan pendek yang diikuti dengan serangkaian kata deskriptif yang dipisahkan dengan tanda hubung. Misalnya,
AM-xxx
untuk kebijakanAssignMessage. Lihat juga alat apigeelint. - Gunakan ekstensi yang tepat untuk file resource,
.js
untuk JavaScript,.py
untuk python, dan.jar
untuk file JAR Java. - Nama variabel harus konsisten. Jika Anda memilih gaya, seperti camelCase atau under_score, gunakan gaya tersebut di seluruh proxy API.
- Gunakan awalan variabel, jika memungkinkan, untuk mengatur variabel berdasarkan tujuannya, misalnya,
Consumer.username
danConsumer.password
.
Pengembangan proxy API
Pertimbangan Desain Awal
- Untuk panduan tentang desain RESTful API, download e-book Desain Web API: The Missing Link.
- Manfaatkan kebijakan dan fungsionalitas Apigee jika memungkinkan untuk membuat proxy API. Hindari coding semua logika proxy di resource JavaScript, Java, atau Python.
- Membangun Flow secara terorganisir. Beberapa Flow, masing-masing dengan satu kondisi, lebih disukai daripada beberapa lampiran bersyarat pada PreFlow dan Postflow yang sama.
- Sebagai 'failsafe', buat proxy API default dengan ProxyEndpoint BasePath sebesar
/
. API ini dapat digunakan untuk mengalihkan permintaan API dasar ke situs developer, untuk menampilkan respons kustom, atau melakukan tindakan lain yang lebih berguna daripada menampilkanmessaging.adaptors.http.flow.ApplicationNotFound
default.
- Gunakan resource TargetServer untuk memisahkan konfigurasi TargetEndpoint dari URL konkret, yang mendukung promosi di seluruh lingkungan.
Lihat Load balancing di berbagai server backend. - Jika Anda memiliki beberapa RouteRules, buat satu aturan sebagai 'default', yaitu, sebagai RouteRule tanpa kondisi. Pastikan RouteRule default ditetapkan terakhir dalam daftar Rute bersyarat. RouteRules dievaluasi dari atas ke bawah di ProxyEndpoint. Lihat Referensi konfigurasi proxy API.
- Ukuran paket proxy API: Paket proxy API tidak boleh lebih dari 15 MB.
- Pembuatan versi API: Untuk pendapat dan rekomendasi Apigee tentang pembuatan versi API, lihat Pembuatan Versi dalam e-book Desain API Web: Link yang Hilang.
Mengaktifkan CORS
Sebelum memublikasikan API, Anda harus menambahkan kebijakan CORS ke permintaan PreFlow dari ProxyEndpoint untuk mendukung permintaan lintas origin sisi klien.
CORS (Cross-origin resource sharing) adalah mekanisme standar yang memungkinkan panggilan XMLHttpRequest (XHR) JavaScript yang dieksekusi di halaman web berinteraksi dengan resource dari domain non-origin. CORS adalah solusi yang umumnya diimplementasikan untuk kebijakan asal yang sama yang diterapkan oleh semua browser. Misalnya, jika Anda melakukan panggilan XHR ke Twitter API dari kode JavaScript yang dieksekusi di browser Anda, panggilan akan gagal. Hal ini karena domain yang menayangkan halaman ke browser Anda tidak sama dengan domain yang menayangkan Twitter API. CORS menyediakan solusi untuk masalah ini dengan memungkinkan server ikut serta jika ingin menyediakan resource berbagi resource lintas origin.
Untuk informasi tentang cara mengaktifkan CORS pada proxy API sebelum memublikasikan API, lihat Menambahkan dukungan CORS ke proxy API.
Ukuran payload pesan
Untuk mencegah masalah memori di Apigee, ukuran payload pesan dibatasi hingga 10 MB. Melebihi ukuran tersebut akan menghasilkan error protocol.http.TooBigBody
.
Masalah ini juga dibahas dalam Error saat meminta/menampilkan payload besar dengan proxy Apigee.
Berikut adalah strategi yang direkomendasikan untuk menangani ukuran pesan besar di Apigee:
- Streaming permintaan dan respons. Perlu diperhatikan bahwa saat Anda melakukan streaming, kebijakan tidak lagi memiliki akses ke konten pesan. Lihat Permintaan dan respons streaming.
Penanganan Kesalahan
- Memanfaatkan FaultRules untuk menangani semua penanganan fault. (Kebijakan RaiseFault digunakan untuk menghentikan Flow pesan dan mengirim pemrosesan ke Alur FaultRules.)
- Dalam Flow FaultRules, gunakan kebijakanAssignMessage untuk membuat respons fault, bukan kebijakan RaiseFault. Jalankan kebijakan TetapkanMessage secara bersyarat berdasarkan jenis kesalahan yang terjadi.
- Selalu sertakan pengendali kesalahan 'catch-all' default sehingga kesalahan yang dihasilkan sistem dapat dipetakan ke format respons kesalahan yang ditentukan pelanggan.
- Jika memungkinkan, selalu buat respons fault sesuai dengan format standar yang tersedia di perusahaan atau project Anda.
- Gunakan pesan error yang bermakna dan dapat dibaca manusia, yang menyarankan solusi untuk kondisi error.
Lihat Menangani kesalahan.
Persistensi
Peta Kunci/Nilai
- Gunakan peta kunci/nilai hanya untuk set data terbatas. Penyimpanan data ini tidak dirancang untuk menjadi penyimpanan data jangka panjang.
- Pertimbangkan performa saat menggunakan peta kunci/nilai karena informasi ini disimpan dalam database Cassandra.
Lihat kebijakan KeyValueMapOperations.
Menyimpan ke Cache Respons
- Jangan mengisi cache respons jika responsnya tidak berhasil atau jika permintaannya bukan GET. Pembuatan, pembaruan, dan penghapusan tidak boleh di-cache.
<SkipCachePopulation>response.status.code != 200 or request.verb != "GET"</SkipCachePopulation>
- Mengisi cache dengan satu jenis konten yang konsisten (misalnya, XML atau JSON). Setelah mengambil entri responseCache, lakukan konversi ke jenis konten yang diperlukan dengan JSONtoXML atau XMLToJSON. Tindakan ini akan mencegah penyimpanan data dua kali, tiga kali, atau lebih.
- Pastikan kunci cache cukup untuk persyaratan penyimpanan dalam cache. Dalam banyak kasus,
request.querystring
dapat digunakan sebagai ID unik. - Jangan menyertakan kunci API (
client_id
) di kunci cache, kecuali jika diperlukan secara eksplisit. Sering kali, API yang hanya diamankan dengan kunci akan menampilkan data yang sama ke semua klien untuk permintaan tertentu. Menyimpan nilai yang sama untuk sejumlah entri berdasarkan kunci API tidaklah efisien. - Setel interval habis masa berlaku cache yang sesuai untuk menghindari pembacaan yang kotor.
- Jika memungkinkan, cobalah untuk membuat kebijakan cache respons yang mengisi cache dieksekusi
di PostFlow respons ProxyEndpoint terlambat. Dengan kata lain, jalankan eksekusi
setelah langkah-langkah penerjemahan dan mediasi, termasuk mediasi berbasis JavaScript dan konversi
antara JSON dan XML. Dengan meng-cache data yang dimediasi, Anda terhindar dari biaya performa dalam menjalankan
langkah mediasi setiap kali mengambil data yang di-cache.
Perhatikan bahwa sebaiknya Anda meng-cache data yang tidak dimediasi jika mediasi menghasilkan respons yang berbeda dari permintaan ke permintaan.
- Kebijakan cache respons untuk mencari entri cache harus terjadi dalam PreFlow permintaan ProxyEndpoint. Hindari menerapkan terlalu banyak logika, selain pembuatan kunci cache, sebelum menampilkan entri cache. Jika tidak, manfaat penyimpanan dalam cache akan diminimalkan.
- Secara umum, Anda harus selalu menjaga pencarian cache respons sedekat mungkin dengan permintaan klien. Sebaliknya, Anda harus menjaga populasi cache respons sedekat mungkin dengan respons klien.
- Saat menggunakan beberapa kebijakan cache respons yang berbeda dalam proxy, ikuti panduan ini
untuk memastikan perilaku yang berbeda bagi setiap kebijakan:
- Menjalankan setiap kebijakan berdasarkan kondisi yang saling eksklusif. Tindakan ini akan membantu memastikan bahwa hanya satu dari beberapa kebijakan cache respons yang dijalankan.
- Menentukan resource cache yang berbeda untuk setiap kebijakan cache respons. Anda menentukan resource
cache dalam elemen
<CacheResource>
kebijakan.
Lihat kebijakan ResponsCache.
Kebijakan dan kode kustom
Kebijakan atau kode kustom?
- Gunakan kebijakan bawaan terlebih dahulu (jika memungkinkan). Kebijakan Apigee telah melalui proses hardening, dioptimalkan, dan didukung. Misalnya, gunakan kebijakan kebijakanAssignMessage dan kebijakan ExtractVariables standar, bukan JavaScript (jika memungkinkan) untuk membuat payload, mengekstrak informasi dari payload (XPath, JSONPath), dan sebagainya.
- JavaScript lebih disukai daripada Python dan Java. Namun, jika performa merupakan persyaratan utamanya, Java harus digunakan daripada JavaScript.
JavaScript
- Gunakan JavaScript jika lebih intuitif daripada kebijakan Apigee (misalnya, saat menetapkan
target.url
untuk berbagai kombinasi URI yang berbeda). - Penguraian payload yang kompleks seperti iterasi melalui objek JSON dan encoding/decoding Base64.
- Kebijakan JavaScript memiliki batas waktu, sehingga loop tanpa batas diblokir.
- Selalu gunakan Langkah JavaScript dan letakkan file dalam folder resource
jsc
. Jenis kebijakan JavaScript mengompilasi kode pada waktu deployment.
Java
- Gunakan Java jika performa adalah prioritas tertinggi, atau jika logika tidak dapat diterapkan dalam JavaScript.
- Sertakan file sumber Java dalam pelacakan kode sumber.
Lihat kebijakan JavaCallout untuk mendapatkan informasi tentang penggunaan Java di proxy API.
Python
- Jangan gunakan Python kecuali jika benar-benar diperlukan. Skrip Python dapat menimbulkan bottleneck performa untuk eksekusi sederhana, seperti yang ditafsirkan saat runtime.
Panggilan Skrip (Java, JavaScript, Python)
- Gunakan try/catch global, atau yang setara.
- Menampilkan pengecualian yang berarti dan menangkapnya dengan benar untuk digunakan dalam respons fault.
- Lempar dan tangkap pengecualian lebih awal. Jangan gunakan try/catch global untuk menangani semua pengecualian.
- Lakukan pemeriksaan null dan yang tidak ditentukan, jika diperlukan. Contoh kapan harus melakukannya adalah saat mengambil variabel alur opsional.
- Hindari membuat permintaan HTTP/S di dalam info skrip. Sebagai gantinya, gunakan kebijakan ServiceCallout karena kebijakan tersebut menangani koneksi dengan baik.
JavaScript
- JavaScript di Platform API mendukung XML melalui E4X.
Lihat model objek JavaScript.
Java
- Saat mengakses payload pesan, coba gunakan
context.getMessage()
vs.context.getResponseMessage
ataucontext.getRequestMessage
. Hal ini memastikan bahwa kode dapat mengambil payload, baik dalam alur permintaan maupun respons. - Impor library ke organisasi atau lingkungan Apigee dan jangan sertakan ini dalam file JAR. Tindakan ini akan mengurangi ukuran paket dan memungkinkan file JAR lain mengakses repositori library yang sama.
- Impor file JAR menggunakan API resource Apigee, bukan menyertakannya dalam folder resource proxy API. Hal ini akan mengurangi waktu deployment dan memungkinkan file JAR yang sama direferensikan oleh beberapa proxy API. Manfaat lainnya adalah isolasi loader class.
- Jangan gunakan Java untuk penanganan resource (misalnya membuat dan mengelola kumpulan thread).
Python
- Tampilkan pengecualian yang berarti dan tangkap pengecualian ini dengan benar untuk digunakan dalam respons kesalahan Apigee
Lihat kebijakan PythonScript.
ServiceCallouts
- Ada banyak kasus penggunaan yang valid untuk penggunaan perantaian proxy, di mana Anda menggunakan pemanggilan layanan dalam
satu proxy API untuk memanggil proxy API lainnya. Jika Anda menggunakan perantaian proxy, pastikan untuk menghindari pemanggilan rekursif infinite loop ke proxy API yang sama.
Jika Anda terhubung antar-proxy yang berada di organisasi dan lingkungan yang sama, pastikan Anda melihat Membuat rantai proxy API bersama-sama untuk mengetahui informasi selengkapnya tentang penerapan koneksi lokal untuk menghindari overhead jaringan yang tidak perlu.
- Buat pesan permintaan ServiceCallout menggunakan kebijakan TetapkanMessage, dan isi objek permintaan di variabel pesan. (Ini termasuk menetapkan payload, jalur, dan metode permintaan.)
- URL yang dikonfigurasi dalam kebijakan memerlukan spesifikasi protokol. Artinya,
bagian protokol dari URL,
https://
, misalnya, tidak dapat ditentukan oleh variabel. Selain itu, Anda harus menggunakan variabel terpisah untuk bagian domain URL dan seluruh URL. Contoh:https://example.com
. - Simpan objek respons untuk ServiceCallout dalam variabel pesan terpisah. Selanjutnya, Anda dapat mengurai variabel pesan dan mempertahankan payload pesan asli agar tetap utuh untuk digunakan oleh kebijakan lain.
Lihat kebijakan InfoService.
Mengakses entity
Kebijakan AccessEntity
- Untuk performa yang lebih baik, cari aplikasi menurut
uuid
, bukan nama aplikasi.
Lihat kebijakan AccessEntity.
Logging
- Gunakan kebijakan syslog yang umum di semua paket dan dalam satu paket. Tindakan ini akan mempertahankan format logging yang konsisten.
Lihat kebijakan MessageLogging.
Pemantauan
Pelanggan cloud tidak perlu memeriksa setiap komponen Apigee (Router, Message Processors, dan sebagainya). Tim Operasi Global Apigee memantau semua komponen secara menyeluruh, beserta health check API, berdasarkan permintaan health check oleh pelanggan.
Analisis Apigee
Analytics dapat memberikan pemantauan API yang tidak penting saat persentase error diukur.
Lihat Dasbor Analytics.
Men-debug
Alat rekaman aktivitas di UI Apigee berguna untuk men-debug masalah API runtime, selama operasi produksi atau pengembangan API.
Lihat Menggunakan alat Debug.
Keamanan
- Gunakan kebijakan pembatasan alamat IP untuk membatasi akses ke lingkungan pengujian Anda. Izinkan akses untuk alamat IP mesin atau lingkungan pengembangan Anda, dan larang yang lainnya. Lihat kebijakan AccessControl.
- Selalu terapkan kebijakan perlindungan konten (JSON dan atau XML) ke proxy API yang di-deploy ke produksi. Lihat kebijakan JSONThreatProtection.
- Lihat topik berikut untuk praktik terbaik keamanan lainnya:
Logika Kustom di Proxy API
Persyaratan umum saat membuat Proxy API adalah menyertakan beberapa logika untuk memproses permintaan dan/atau respons. Meskipun banyak persyaratan dapat dipenuhi dari serangkaian langkah/tindakan/kebijakan yang telah ditentukan seperti memverifikasi token, menerapkan kuota, atau merespons dengan objek yang di-cache, sering kali persyaratan tersebut memerlukan akses ke kemampuan pemrograman. Misalnya, mencari lokasi (endpoint) dari tabel perutean berdasarkan kunci yang ditemukan dalam permintaan dan secara dinamis menerapkan endpoint target atau metode autentikasi khusus/kepemilikan, dll.
Apigee memberi developer beberapa opsi untuk menangani logika kustom tersebut. Dokumen ini akan menjelaskan opsi-opsi tersebut dan kapan harus menggunakannya:
Kebijakan | Kasus penggunaan kebijakan |
---|---|
JavaScript dan PythonScript |
Kapan digunakan:
Kapan tidak boleh digunakan:
Praktik Terbaik: Apigee lebih merekomendasikan JavaScript daripada PythonScript, karena JavaScript menawarkan performa yang lebih baik. |
JavaCallout |
Kapan digunakan:
Kapan tidak boleh digunakan:
|
ExternalCallout |
Kapan digunakan:
Jika tidak digunakan:
|
ServiceCallout |
Kapan digunakan:
Jika tidak digunakan:
|
Ringkasnya:
- Jika logikanya sederhana atau mudah, gunakan JavaScript (sebaiknya) atau PythonScript.
- Jika logika inline memerlukan performa yang lebih baik daripada JavaScript atau PythonScript, gunakan JavaCallout.
- Jika logika harus dieksternalkan, gunakan ExternalCallout.
- Jika Anda sudah memiliki implementasi eksternal dan/atau developer sudah memahami REST, gunakan ServiceCallout.
Gambar berikut mengilustrasikan proses ini: