Praktik terbaik untuk desain dan pengembangan proxy API dengan Apigee

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat Dokumentasi Apigee Edge.

Dokumen ini memberikan serangkaian praktik terbaik untuk mengembangkan proxy API dengan Apigee.

Topik-topik yang dibahas di sini meliputi desain, {i>coding<i}, penggunaan kebijakan, pemantauan, dan proses debug. Informasi tersebut dikumpulkan oleh pengalaman developer bekerja sama dengan Apigee untuk menerapkan program API yang sukses. Ini adalah dokumen hidup dan akan diperbarui dari waktu ke waktu.

Selain panduan di sini, Anda mungkin juga mendapatkan manfaat dari Pengantar anti-pola.

Standar pengembangan

Komentar dan Dokumentasi

• Memberikan komentar inline di ProxyEndpoint dan TargetEndpoint konfigurasi standar. Komentar meningkatkan keterbacaan untuk Flow, terutama jika nama file kebijakan tidak cukup deskriptif untuk mengekspresikan fungsi yang mendasari Alur.
• Jadikan komentar bermanfaat. Hindari komentar yang jelas.
• Gunakan indentasi, spasi, perataan vertikal, dan sebagainya yang konsisten.

Coding dengan gaya 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 mengontrol sumber sehingga developer dapat menyinkronkannya dan menggunakannya dalam pengembangan proxy mereka sendiri lingkungan fleksibel App Engine.

• 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 dipanggil ExtractVariables.ExtractRequestParameters.
• Bersihkan kebijakan dan resource yang tidak digunakan (JavaScript, Java, XSLT, ) dari proxy API, terutama resource besar yang berpotensi memperlambat impor dan deployment prosedur standar.

Konvensi Penamaan

• Atribut name kebijakan dan nama file kebijakan XML harus sama.
• Atribut name kebijakan Skrip dan kebijakan ServiceKeterangan dan nama file resource harus sama.
• DisplayName harus menjelaskan fungsi kebijakan secara akurat kepada seseorang yang belum pernah bekerja dengan proxy API itu sebelumnya.
• Beri nama kebijakan sesuai dengan fungsinya. Apigee merekomendasikan agar Anda membangun konvensi penamaan yang konsisten untuk kebijakan Anda. Misalnya, gunakan awalan pendek yang diikuti dengan rangkaian kata deskriptif yang dipisahkan oleh tanda hubung. Misalnya, AM-xxx untuk kebijakan MenetapkanMessage. Lihat juga apigeelint alat.
• 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 garis bawah, gunakan di seluruh proxy API.
• Gunakan awalan variabel, jika memungkinkan, untuk mengatur variabel berdasarkan tujuannya, untuk contoh, Consumer.username dan Consumer.password.

Pengembangan proxy API

Pertimbangan Desain Awal

Peringatan: Jangan panggil Apigee API dari di dalam proxy API. API digunakan untuk tujuan pengelolaan administratif, bukan API logika alur. Karena entri cache berumur lebih lama di server API Apigee, Anda mungkin tidak melihat memperbarui data dengan segera di aliran {i>proxy<i} Anda, terutama jika Anda melakukan penulisan cepat dan kemudian membaca. Solusi coding untuk perilaku ini dapat memengaruhi proxy Anda tingkat tinggi.

Menggunakan kebijakan dalam proxy API.

• Untuk mendapatkan panduan tentang desain RESTful API, download e-book Desain Web API: Link yang Hilang.
• Manfaatkan kebijakan dan fungsi Apigee jika memungkinkan untuk membangun proxy API. Hindari melakukan coding untuk semua logika proxy di resource JavaScript, Java, atau Python.
• Membangun Flow secara teratur. Beberapa Flow, masing-masing dengan satu kondisi, lebih disukai untuk beberapa lampiran bersyarat untuk {i> PreFlow<i} dan {i>Postflow<i} yang sama.
• Sebagai 'failsafe', buat proxy API default dengan ProxyEndpoint BasePath sebesar /. Ini bisa digunakan untuk mengalihkan permintaan API dasar ke situs developer, untuk menampilkan respons kustom, atau lakukan tindakan lain yang lebih berguna daripada menampilkan messaging.adaptors.http.flow.ApplicationNotFound.
• Untuk performa yang optimal, Apigee merekomendasikan untuk tidak menggunakan lebih dari 3.000 basepath proxy API per lingkungan Apigee atau grup lingkungan. Jika rekomendasi ini terlampaui, latensi untuk semua deployment proxy API baru dan yang sudah ada dapat meningkat.
• Menggunakan resource TargetServer untuk memisahkan konfigurasi TargetEndpoint dari URL konkret, mendukung promosi di seluruh lingkungan.
  Lihat Load balancing di seluruh server backend.
• Jika Anda memiliki beberapa RouteRules, buat satu sebagai 'default', yaitu sebagai RouteRule dengan tanpa kondisi. Pastikan RouteRule default ditentukan terakhir dalam daftar kondisional Rute. 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 di Web API Design: The Missing Link e-book.

Mengaktifkan CORS

Sebelum memublikasikan API, Anda harus menambahkan kebijakan CORS ke meminta PreFlow ProxyEndpoint untuk mendukung permintaan lintas origin sisi klien.

CORS (Cross-origin resource sharing) adalah mekanisme standar yang memungkinkan JavaScript Panggilan XMLHttpRequest (XHR) yang dijalankan di halaman web untuk berinteraksi dengan resource dari non-asal domain. CORS adalah solusi yang umum diimplementasikan untuk kebijakan origin yang sama yang diterapkan oleh semua browser. Misalnya, jika Anda membuat panggilan XHR ke Twitter API dari JavaScript kode yang dieksekusi di browser, panggilan akan gagal. Hal ini karena domain yang menayangkan halaman ke browser Anda tidak sama dengan domain yang menyajikan Twitter API. CORS memberikan solusi terhadap masalah ini dengan mengizinkan server untuk ikut serta jika ingin menyediakan resource lintas asal berbagi.

Untuk mengetahui informasi tentang cara mengaktifkan CORS di proxy API sebelum memublikasikan API, lihat Menambahkan CORS dukungan terhadap proxy API.

Catatan: Sebagian besar browser modern mendukung CORS. Anda dapat menemukan daftar lengkap respons browser di sini. Untuk penjelasan mendalam tentang CORS, lihat Cross-Origin Resource Sharing W3C Rekomendasi.

Jika Anda menggunakan cache di proxy API, pastikan respons kebijakan CORS tidak di-cache.

Ukuran payload pesan

Untuk mencegah masalah memori di Apigee, ukuran payload pesan dibatasi hingga 10 MB. Melebihi batas ukuran akan menghasilkan error protocol.http.TooBigBody.

Masalah ini juga dibahas di Terjadi 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 diketahui bahwa saat Anda melakukan streaming, kebijakan tidak lagi memiliki akses ke isi pesan. Lihat Streaming permintaan dan respons.

Penanganan Fault

• Memanfaatkan FaultRules untuk menangani semua penanganan kesalahan. (Kebijakan RaiseFault digunakan untuk menghentikan alur pesan dan mengirim pemrosesan ke FaultRules Flow.)
• Dalam FaultRules Flow, gunakan kebijakanAssignMessage untuk membuat respons fault, bukan Kebijakan RaiseFault. Mengeksekusi kebijakan MenetapkanMessage secara bersyarat berdasarkan jenis kesalahan yang apa yang terjadi.
• Selalu sertakan 'catch-all' default pengendali kesalahan sehingga kesalahan yang dihasilkan sistem dapat dipetakan ke format respons kesalahan yang ditentukan pelanggan.
• Jika memungkinkan, selalu buat respons kesalahan cocok dengan format standar yang tersedia di perusahaan atau proyek tertentu.
• Menggunakan pesan error yang bermakna dan dapat dibaca manusia, yang menyarankan solusi untuk error tersebut .

Lihat Menangani kesalahan.

Persistensi

Peta Kunci/Nilai

• Gunakan peta kunci/nilai hanya untuk set data terbatas. Model tidak dirancang untuk menjadi data jangka panjang Anda.
• Pertimbangkan performa saat menggunakan peta kunci/nilai karena informasi ini disimpan di dari database Cassandra.

Lihat kebijakan KeyValueMapOperations.

Menyimpan ke Cache Respons

• Jangan mengisi cache respons jika respons tidak berhasil atau jika permintaan bukan GET. Pembuatan, pembaruan, dan penghapusan tidak boleh di-cache. <SkipCachePopulation>response.status.code != 200 or request.verb != "GET"</SkipCachePopulation>
• Isi cache dengan satu jenis konten yang konsisten (misalnya, XML atau JSON). Sesudah mengambil entri responseCache, lalu mengonversinya ke jenis konten yang diperlukan dengan JSONtoXML atau XMLToJSON tertentu. Tindakan ini akan mencegah penyimpanan data ganda, rangkap tiga, atau lebih.
• Pastikan kunci cache cukup untuk persyaratan caching. Dalam banyak kasus, request.querystring dapat digunakan sebagai ID unik.
• Jangan sertakan kunci API (client_id) di kunci cache, kecuali secara eksplisit tidak diperlukan. Sering kali, API yang hanya diamankan oleh kunci akan menampilkan data yang sama ke semua klien untuk permintaan tertentu. Tidak efisien untuk menyimpan nilai yang sama untuk sejumlah entri berdasarkan Kunci API.
• Tetapkan interval habis masa berlaku cache yang sesuai untuk menghindari pembacaan yang kotor.
• Jika memungkinkan, pastikan kebijakan cache respons yang mengisi cache dijalankan di PostFlow respons ProxyEndpoint. Dengan kata lain, perintahkan untuk mengeksekusi setelah langkah penerjemahan dan mediasi, termasuk konversi dan mediasi berbasis JavaScript antara JSON dan XML. Dengan meng-cache data yang dimediasi, Anda menghindari biaya performa saat menjalankan langkah mediasi setiap kali Anda mengambil data yang di-cache.

  Perlu diketahui bahwa Anda mungkin ingin meng-cache data yang tidak dimediasi jika mediasi menghasilkan respons yang berbeda untuk setiap permintaan.

• Kebijakan cache respons untuk mencari entri cache harus terjadi di ProxyEndpoint meminta PreFlow. Hindari menerapkan terlalu banyak logika, selain pembuatan kunci cache, sebelum mengembalikan entri cache. Jika tidak, manfaat penyimpanan dalam cache akan berkurang.
• Secara umum, Anda harus selalu menyimpan pencarian cache respons sedekat mungkin dengan permintaan klien mungkin. Sebaliknya, Anda harus menyimpan populasi cache respons sedekat mungkin dengan klien respons yang sebaik mungkin.
• Saat menggunakan beberapa kebijakan cache respons yang berbeda di suatu proxy, ikuti panduan berikut untuk memastikan perilaku diskret untuk masing-masing:
  • Jalankan setiap kebijakan berdasarkan kondisi yang sama-sama bersifat eksklusif. Hal ini akan membantu memastikan bahwa hanya satu dari beberapa kebijakan cache respons yang dijalankan.
  • Menetapkan resource cache yang berbeda untuk setiap kebijakan cache respons. Anda yang menentukan cache resource 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. Sebagai contoh, gunakan kebijakan TetapkanMessage standar dan Kebijakan ExtractVariables kebijakan dan bukan JavaScript (jika memungkinkan) untuk membuat payload, mengekstrak informasi dari payload (XPath, JSONPath), dan seterusnya.
• JavaScript lebih disukai daripada Python dan Java. Namun, jika performa adalah , Java harus digunakan di atas JavaScript.

JavaScript

• Gunakan JavaScript jika lebih intuitif daripada kebijakan Apigee (misalnya, saat menetapkan target.url untuk berbagai kombinasi URI).
• Penguraian payload yang kompleks seperti melakukan iterasi melalui objek JSON dan Base64 encoding/dekode.
• Kebijakan JavaScript memiliki batas waktu, sehingga loop tanpa batas diblokir.
• Selalu gunakan Langkah-Langkah JavaScript dan letakkan file di folder resource jsc. Jenis Kebijakan JavaScript mengompilasi kode terlebih dahulu pada waktu deployment.

Java

Peringatan: Untuk Info Java, ketergantungan pada library Java yang yang disertakan dengan Apigee tidak didukung. Library tersebut ditujukan untuk Apigee fungsi produk saja, dan tidak ada jaminan bahwa library akan tersedia mulai dari rilis hingga rilis.

• Gunakan Java jika performa merupakan prioritas tertinggi, atau jika logika tidak dapat diimplementasikan di pada JavaScript.
• Menyertakan file sumber Java dalam pelacakan kode sumber.

Lihat kebijakan Javacallout untuk mengetahui informasi tentang penggunaan Java pada proxy API.

Python

• Jangan gunakan Python kecuali jika benar-benar diperlukan. Skrip Python dapat meningkatkan performa bottleneck untuk eksekusi sederhana, seperti yang ditafsirkan pada runtime.

Pemanggilan Skrip (Java, JavaScript, Python)

• Gunakan try/catch global, atau yang setara.
• Tampilkan pengecualian yang bermakna dan tangkap ini dengan benar untuk digunakan dalam respons kesalahan.
• Tampilkan dan tangkap pengecualian lebih awal. Jangan gunakan try/catch global untuk menangani semua setiap pengecualian.
• Lakukan pemeriksaan null dan tidak ditentukan, jika diperlukan. Contoh waktu yang tepat untuk melakukannya adalah mengambil variabel alur opsional.
• Hindari membuat permintaan HTTP/S di dalam pemanggilan skrip. Sebagai gantinya, gunakan Kebijakan ServiceKeterangan karena kebijakan ini menangani koneksi dengan baik.

JavaScript

• JavaScript di Platform API mendukung XML melalui E4X.

Lihat model objek JavaScript.

Java

Peringatan: Untuk Info Java, ketergantungan pada library Java yang yang disertakan dengan Apigee tidak didukung. Library tersebut ditujukan untuk fungsi produk Apigee saja, dan tidak ada jaminan bahwa library akan tersedia mulai dari rilis hingga rilis.

• Saat mengakses payload pesan, coba gunakan context.getMessage() vs. context.getResponseMessage atau context.getRequestMessage. Hal ini memastikan kode bisa mengambil payload, dalam alur permintaan dan respons.
• Impor library ke organisasi atau lingkungan Apigee dan jangan sertakan library tersebut di file JAR. Tindakan ini akan mengurangi ukuran paket dan akan memungkinkan file JAR lain mengakses library yang sama repositori resource.
• Mengimpor file JAR menggunakan API resource Apigee, bukan menyertakannya di dalam API folder resource proxy. Hal ini akan mengurangi waktu deployment dan memungkinkan file JAR yang sama yang direferensikan oleh beberapa proxy API. Manfaat lainnya adalah isolasi loader class.
• Jangan gunakan Java untuk penanganan resource (misalnya, membuat dan mengelola thread gabungan).

Python

• Tampilkan pengecualian yang bermakna dan tangkap ini dengan benar untuk digunakan dalam kesalahan Apigee respons

Lihat kebijakan PythonScript.

ServiceCallouts

• Ada banyak kasus penggunaan yang valid terkait penggunaan perantaian proxy, di mana Anda menggunakan info layanan dalam satu proxy API untuk memanggil proxy API lainnya. Jika Anda menggunakan perantaian proxy, pastikan untuk menghindari tak terbatas melakukan loop pemanggilan rekursif kembali ke proxy API yang sama.

  Jika Anda terhubung di antara proxy yang berada di organisasi dan lingkungan yang sama, pasti melihat API rantai proxy bersama-sama untuk mengetahui lebih lanjut tentang penerapan koneksi lokal overhead jaringan.

• Membuat pesan permintaan ServiceInfo menggunakan kebijakan MenetapkanMessage, dan mengisi 'request' dalam variabel pesan. (Ini termasuk pengaturan {i>payload<i} permintaan, jalur, dan method.)
• URL yang dikonfigurasi dalam kebijakan memerlukan spesifikasi protokol, artinya bagian protokol URL, misalnya https://, tidak dapat ditentukan oleh variabel. Selain itu, Anda harus menggunakan variabel terpisah untuk bagian domain URL dan untuk URL lainnya. Contoh: https://example.com.
• Simpan objek respons untuk ServiceInfo dalam variabel pesan terpisah. Anda kemudian dapat mengurai variabel pesan dan mempertahankan payload pesan asli agar tetap utuh untuk digunakan oleh kebijakan izin yang relevan.

Lihat kebijakan ServiceInfo.

Mengakses entity

Kebijakan AccessEntity

• Untuk performa yang lebih baik, cari aplikasi berdasarkan uuid, bukan nama aplikasi.

Lihat kebijakan AccessEntity.

Logging

• Gunakan kebijakan syslog umum di seluruh paket dan dalam paket yang sama. Ini akan membuat format pencatatan yang konsisten.

Lihat kebijakan MessageLogging.

Pemantauan

Pelanggan cloud tidak wajib memeriksa setiap komponen Apigee (Router, Pemroses Pesan, dan sebagainya). Tim Operasi Global Apigee memantau secara menyeluruh komponen, beserta health check API, berdasarkan permintaan health check yang diberikan oleh pelanggan.

Analisis Apigee

Analytics dapat menyediakan pemantauan API yang tidak penting saat persentase error diukur.

Lihat Analytics dasbor.

Debug

Alat pelacakan di UI Apigee berguna untuk men-debug masalah API runtime, selama pengembangan atau produksi 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 melarang yang lainnya. Lihat kebijakan AccessControl.
• Selalu terapkan kebijakan perlindungan konten (JSON dan atau XML) ke proxy API yang di-deploy ke production. Lihat kebijakan JSONThreatProtection.
• Lihat topik berikut untuk praktik terbaik keamanan lainnya:
  • Kebijakan XMLThreatProtection
  • Kebijakan RegularExpressionProtection
  • Kebijakan SOAPMessageValidation

Logika Khusus di Proxy API

Persyaratan umum saat membangun Proxy API adalah menyertakan beberapa logika untuk memproses permintaan dan/atau tanggapan. Meskipun banyak persyaratan dapat dipenuhi dari serangkaian langkah/tindakan/kebijakan seperti memverifikasi token atau menerapkan kuota atau merespons dengan , sering kali mungkin 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/eksklusif, dll.

Apigee memberi developer beberapa opsi untuk menangani logika kustom tersebut. Dokumen ini kita akan mempelajari opsi tersebut dan kapan harus menggunakan:

Kebijakan	Kasus penggunaan kebijakan
JavaScript dan PythonScript	Kapan digunakan: Kebijakan JavaScript dan PythonScript memiliki kemampuan yang setara. Aplikasi keakraban dalam suatu bahasa biasanya menjadi motivasi untuk memilih satu bahasa dari yang lain. Kebijakan JavaScript dan PythonScript paling cocok untuk logika pemrosesan inline yang tidak terlalu rumit dan tidak memerlukan penggunaan library pihak ketiga. Kebijakan ini tidak berperforma sama tingginya dengan kebijakan Javacallout. Kapan tidak digunakan: Gateway API Apigee bukan server aplikasi (juga tidak menyediakan Runtime JavaScript seperti node.js). Jika info selalu memerlukan waktu lebih dari satu detik untuk memproses, logika kemungkinan besar tidak termasuk dalam {i>gateway<i} dan harus menjadi bagian dari layanan yang mendasarinya. Praktik Terbaik: Apigee merekomendasikan JavaScript daripada PythonScript, karena JavaScript menawarkan performa yang lebih baik.
JavaCallout	Kapan digunakan: Performa pemrosesan logika inline sangat penting. Library Java yang ada menyediakan banyak logika. Kapan tidak digunakan: Gateway API Apigee bukan server aplikasi dan tidak dimaksudkan untuk memuat seperti Spring, JEE, dll. Jika info biasanya menghabiskan waktu lebih dari satu detik untuk diproses, logika dapat dianggap sebagai fungsional (logika bisnis). Pertimbangkan untuk melakukan eksternalisasi sebagai layanan. Untuk melindungi gateway API Apigee dari penyalahgunaan, terdapat pembatasan pada jenis kode yang dapat dieksekusi. Misalnya, kode Java yang mencoba mengakses perpustakaan kriptografis, atau mengakses sistem file, diblokir dari eksekusi. Aplikasi Java, terutama yang bergantung pada pustaka pihak ketiga, dapat membawa dalam banyak (dan besar) file JAR. Hal ini dapat memperlambat waktu booting gateway.
ExternalCallout	Kapan digunakan: Idealnya cocok untuk mengeksternalkan logika kustom dan memungkinkan logika kustom untuk mengakses (dan jika perlu, ubah) konteks pesan. Info eksternal menerapkan gRPC dan mungkin memiliki performa yang lebih baik daripada Info Layanan. Saat menggunakan Apigee atau Apigee Hybrid di Google Cloud, pertimbangkan untuk menggunakan Cloud Functions atau Cloud Run untuk menghosting logika tersebut. Sebagai pengganti yang efektif untuk fitur Target yang Dihosting di Apigee Edge. Jika tidak digunakan: Untuk logika ringan yang dapat dieksekusi dengan cepat, secara inline.
ServiceCallout	Kapan digunakan: Logika kompleks paling baik diterapkan di luar gateway. Logika ini dapat memiliki siklus proses (rilis dan pembuatan versi) dan tidak mempengaruhi fungsi gateway. Saat endpoint REST/SOAP/GraphQL sudah ada atau dapat diterapkan dengan mudah Saat menggunakan Apigee atau Apigee Hybrid di Google Cloud, pertimbangkan untuk menggunakan Cloud Functions atau Cloud Run untuk menghosting logika tersebut. Sebagai pengganti yang efektif untuk fitur Target yang Dihosting di Apigee Edge. Jika tidak digunakan: Untuk logika ringan yang dapat dieksekusi dengan cepat, inline Proxy API harus mentransfer konteks (seperti variabel) atau menerima konteks dari implementasi eksternal

Ringkasnya:

1. Jika logika sederhana atau sederhana, gunakan JavaScript (sebaiknya) atau PythonScript.
2. Jika logika inline memerlukan performa yang lebih baik daripada JavaScript atau PythonScript, gunakan Javacallout.
3. Jika logika harus dieksternalkan, gunakan ExternalInfo.
4. Jika Anda sudah memiliki implementasi eksternal dan/atau developer sudah terbiasa dengan REST, gunakan Info Layanan.

Gambar berikut menggambarkan proses ini: