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 yang dibahas di sini mencakup desain, coding, penggunaan kebijakan, pemantauan, dan proses debug. Informasi ini telah dikumpulkan berdasarkan pengalaman developer yang bekerja dengan Apigee untuk menerapkan program API yang sukses. Dokumen ini terus diperbarui dan akan diperbarui dari waktu ke waktu.

Selain panduan di sini, Anda mungkin juga merasa Pengantar antipola berguna.

Standar pengembangan

Komentar dan Dokumentasi

• Berikan komentar inline dalam konfigurasi ProxyEndpoint dan TargetEndpoint. Komentar meningkatkan keterbacaan Flow, terutama jika nama file kebijakan tidak cukup deskriptif untuk mengekspresikan fungsi dasar Flow.
• Buat komentar yang berguna. Hindari komentar yang jelas.
• Gunakan indentasi, spasi, perataan vertikal, dan sebagainya yang konsisten.

Coding gaya framework

Coding gaya framework melibatkan penyimpanan resource proxy API di sistem kontrol versi Anda sendiri untuk digunakan kembali di seluruh lingkungan pengembangan lokal. Misalnya, untuk menggunakan kembali kebijakan, simpan kebijakan tersebut di kontrol sumber sehingga developer dapat menyinkronkannya dan menggunakannya di lingkungan pengembangan proxy mereka sendiri.

• Untuk mengaktifkan DRY (don't repeat yourself), jika memungkinkan, konfigurasi dan skrip kebijakan harus menerapkan 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 Script dan kebijakan ServiceCallout serta nama file resource harus identik.
• DisplayName harus mendeskripsikan 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 singkat yang diikuti dengan urutan kata deskriptif yang dipisahkan dengan tanda hubung. Misalnya, AM-xxx untuk kebijakan AssignMessage. Lihat juga alat apigeelint.
• Gunakan ekstensi yang sesuai 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 dan Consumer.password.

Pengembangan proxy API

Pertimbangan Desain Awal

Peringatan: Jangan panggil Apigee API dari dalam proxy API. API ini digunakan untuk tujuan pengelolaan administratif, bukan logika alur API. Karena entri cache yang berumur lebih lama di server Apigee API, Anda mungkin tidak langsung melihat data yang diperbarui dalam alur proxy, terutama jika Anda melakukan operasi tulis cepat, lalu membaca. Solusi coding untuk perilaku ini dapat memengaruhi performa proxy Anda.

Sebagai gantinya, gunakan policies di proxy API.

• Untuk panduan desain RESTful API, download eBook Desain API Web: Link yang Hilang.
• Manfaatkan kebijakan dan fungsi Apigee jika memungkinkan untuk membuat proxy API. Hindari coding semua logika proxy di resource JavaScript, Java, atau Python.
• Buat Alur dengan cara yang teratur. Beberapa Alur, masing-masing dengan satu kondisi, lebih disukai daripada beberapa lampiran bersyarat ke PreFlow dan Postflow yang sama.
• Sebagai 'failsafe', buat proxy API default dengan BasePath ProxyEndpoint dari /. Ini dapat digunakan untuk mengalihkan permintaan API dasar ke situs developer, untuk menampilkan respons kustom, atau melakukan tindakan lain yang lebih berguna daripada menampilkan messaging.adaptors.http.flow.ApplicationNotFound default.
• Untuk performa yang optimal, Apigee merekomendasikan penggunaan tidak lebih dari 3.000 jalur dasar proxy API per lingkungan atau grup lingkungan Apigee. Melebihi rekomendasi ini dapat menyebabkan peningkatan latensi untuk semua deployment proxy API baru dan yang sudah ada.
• Gunakan resource TargetServer untuk memisahkan konfigurasi TargetEndpoint dari URL konkret, yang mendukung promosi di seluruh lingkungan.
  Lihat Load balancing di seluruh server backend.
• Jika Anda memiliki beberapa RouteRules, buat satu sebagai 'default', yaitu sebagai RouteRule tanpa kondisi. Pastikan RouteRule default ditentukan 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 besar dari 15 MB.
• Pembuatan versi API: Untuk mengetahui pendapat dan rekomendasi Apigee tentang pembuatan versi API, lihat Pembuatan Versi dalam e-book Web API Design: The Missing Link.

Mengaktifkan CORS

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

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

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

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

Jika menggunakan kebijakan cache di proxy API, Anda harus memastikan bahwa respons kebijakan CORS tidak disimpan dalam cache.

Ukuran payload pesan

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

Masalah ini juga dibahas di 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. Perhatikan bahwa saat Anda melakukan streaming, kebijakan tidak lagi memiliki akses ke konten pesan. Lihat Permintaan dan respons streaming.

Penanganan Error

• Manfaatkan FaultRules untuk menangani semua penanganan error. (Kebijakan RaiseFault digunakan untuk menghentikan Flow pesan dan mengirim pemrosesan ke Flow FaultRules.)
• Dalam Alur FaultRules, gunakan kebijakan AssignMessage untuk membuat respons error, bukan kebijakan RaiseFault. Menjalankan kebijakan AssignMessage secara bersyarat berdasarkan jenis error yang terjadi.
• Selalu sertakan pengendali error 'catch-all' default sehingga error yang dihasilkan sistem dapat dipetakan ke format respons error yang ditentukan pelanggan.
• Jika memungkinkan, selalu buat respons error cocok 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 error.

Persistensi

Peta Nilai Kunci

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

Lihat kebijakan KeyValueMapOperations.

Penyimpanan dalam Cache Respons

• Jangan isi cache respons jika respons 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>
• Isi cache dengan satu jenis konten yang konsisten (misalnya, XML atau JSON). Setelah mengambil entri responseCache, konversikan ke jenis konten yang diperlukan dengan JSONtoXML atau XMLToJSON. Tindakan ini akan mencegah penyimpanan data ganda, tiga kali lipat, atau lebih.
• Pastikan kunci cache cukup untuk persyaratan penyimpanan dalam cache. Dalam banyak kasus, request.querystring dapat digunakan sebagai ID unik.
• Jangan sertakan kunci API (client_id) dalam kunci cache, kecuali jika secara eksplisit diperlukan. Sering kali, API yang hanya diamankan dengan kunci akan menampilkan data yang sama kepada semua klien untuk permintaan tertentu. Menyimpan nilai yang sama untuk sejumlah entri berdasarkan kunci API tidak efisien.
• Tetapkan interval habis masa berlaku cache yang sesuai untuk menghindari pembacaan kotor.
• Jika memungkinkan, coba buat kebijakan cache respons yang mengisi cache dijalankan di PostFlow respons ProxyEndpoint selambat mungkin. Dengan kata lain, jalankan setelah langkah terjemahan dan mediasi, termasuk mediasi dan konversi berbasis JavaScript antara JSON dan XML. Dengan menyimpan data mediasi dalam cache, Anda menghindari biaya performa saat menjalankan langkah mediasi setiap kali mengambil data yang di-cache.

  Perhatikan bahwa Anda mungkin ingin 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 di 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 pengisian cache respons sedekat mungkin dengan respons klien.
• Saat menggunakan beberapa kebijakan cache respons yang berbeda di proxy, ikuti panduan ini untuk memastikan perilaku terpisah untuk setiap kebijakan:
  • Jalankan setiap kebijakan berdasarkan kondisi yang saling eksklusif. Tindakan ini akan membantu memastikan bahwa hanya satu dari beberapa kebijakan cache respons yang dieksekusi.
  • Tentukan resource cache yang berbeda untuk setiap kebijakan cache respons. Anda menentukan resource cache di elemen <CacheResource> kebijakan.

Lihat kebijakan ResponseCache.

Kebijakan dan kode kustom

Kebijakan atau kode kustom?

• Gunakan kebijakan bawaan terlebih dahulu (jika memungkinkan). Kebijakan Apigee di-harden, dioptimalkan, dan didukung. Misalnya, gunakan kebijakan AssignMessage policy dan ExtractVariables policy standar, bukan JavaScript (jika memungkinkan) untuk membuat payload, mengekstrak informasi dari payload (XPath, JSONPath), dan sebagainya.
• JavaScript lebih disarankan daripada Python dan Java. Namun, jika performa adalah persyaratan utama, Java harus digunakan daripada JavaScript.

JavaScript

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

Java

Peringatan: Untuk Java Callouts, bergantung pada library Java yang disertakan dengan Apigee tidak didukung. Library tersebut hanya ditujukan untuk fungsi produk Apigee, dan tidak ada jaminan bahwa library akan tersedia dari rilis ke rilis.

• Gunakan Java jika performa adalah prioritas tertinggi, atau jika logika tidak dapat diterapkan dalam JavaScript.
• Menyertakan file sumber Java dalam pelacakan kode sumber.

Lihat kebijakan JavaCallout untuk mengetahui informasi tentang penggunaan Java di proxy API.

Python

• Jangan gunakan Python kecuali jika benar-benar diperlukan. Skrip Python dapat menyebabkan bottleneck performa untuk eksekusi sederhana, karena ditafsirkan saat runtime.

Info Skrip (Java, JavaScript, Python)

• Gunakan try/catch global, atau yang setara.
• Tampilkan pengecualian yang bermakna dan tangkap dengan benar untuk digunakan dalam respons error.
• Menampilkan dan menangkap pengecualian lebih awal. Jangan gunakan try/catch global untuk menangani semua pengecualian.
• Lakukan pemeriksaan null dan undefined, jika diperlukan. Contoh waktu untuk melakukannya adalah saat mengambil variabel alur opsional.
• Hindari membuat permintaan HTTP/S di dalam info skrip. Sebagai gantinya, gunakan kebijakan ServiceCallout karena kebijakan ini menangani koneksi dengan baik.

JavaScript

• JavaScript di Platform API mendukung XML melalui E4X.

Lihat model objek JavaScript.

Java

Peringatan: Untuk Java Callouts, bergantung pada library Java yang disertakan dengan Apigee tidak didukung. Library tersebut hanya untuk fungsi produk Apigee, dan tidak ada jaminan bahwa library akan tersedia dari rilis ke rilis.

• Saat mengakses payload pesan, coba gunakan context.getMessage() vs. context.getResponseMessage atau context.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 library ini dalam file JAR. Hal ini akan mengurangi ukuran paket dan memungkinkan file JAR lain mengakses repositori library yang sama.
• Impor file JAR menggunakan API resource Apigee, bukan menyertakannya di 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

• Menampilkan pengecualian yang bermakna dan menangkapnya dengan benar untuk digunakan dalam respons error Apigee

Lihat kebijakan PythonScript.

ServiceCallouts

• Ada banyak kasus penggunaan yang valid untuk menggunakan rantai proxy, yaitu Anda menggunakan panggilan layanan di satu proxy API untuk memanggil proxy API lain. Jika Anda menggunakan rantai proxy, pastikan untuk menghindari info berulang loop tak terbatas kembali ke proxy API yang sama.

  Jika Anda menghubungkan antar-proxy yang berada dalam organisasi dan lingkungan yang sama, pastikan untuk melihat Menghubungkan proxy API secara berantai untuk mengetahui informasi selengkapnya tentang cara menerapkan koneksi lokal yang menghindari overhead jaringan yang tidak perlu.

• Buat pesan permintaan ServiceCallout menggunakan kebijakan AssignMessage, dan isi objek permintaan dalam variabel pesan. (Tindakan ini mencakup penetapan payload, jalur, dan metode permintaan.)
• URL yang dikonfigurasi dalam kebijakan memerlukan spesifikasi protokol, yang berarti bagian protokol URL, misalnya https://, tidak dapat ditentukan oleh variabel. Selain itu, Anda harus menggunakan variabel terpisah untuk bagian domain URL dan untuk bagian URL lainnya. Contoh: https://example.com.
• Simpan objek respons untuk ServiceCallout dalam variabel pesan terpisah. Kemudian, Anda dapat mengurai variabel pesan dan mempertahankan payload pesan asli agar dapat digunakan oleh kebijakan lain.

Lihat kebijakan ServiceCallout.

Mengakses entity

Kebijakan AccessEntity

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

Lihat kebijakan AccessEntity.

Logging

• Gunakan kebijakan syslog umum di seluruh paket dan dalam paket yang sama. Tindakan ini akan mempertahankan format logging yang konsisten.

Lihat kebijakan MessageLogging.

Pemantauan

Pelanggan Cloud tidak perlu memeriksa setiap komponen Apigee (Router, Message Processor, dan sebagainya). Tim Global Operations Apigee memantau semua komponen secara menyeluruh, bersama dengan health check API, berdasarkan permintaan health check dari pelanggan.

Apigee Analytics

Analytics dapat memberikan pemantauan API non-kritis saat persentase error diukur.

Lihat Dasbor Analytics.

Debug

Alat pelacakan di UI Apigee berguna untuk men-debug masalah API runtime, selama operasi 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 larang semua alamat IP 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 mengetahui praktik terbaik keamanan lainnya:
  • Kebijakan XMLThreatProtection
  • Kebijakan RegularExpressionProtection
  • Kebijakan SOAPMessageValidation

Logika Kustom di Proxy API

Persyaratan umum saat mem-build 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 sebelumnya seperti memverifikasi token atau menerapkan kuota atau merespons dengan objek yang di-cache, salah satunya sering kali memerlukan akses ke kemampuan pemrograman. Misalnya, mencari lokasi (endpoint) dari tabel perutean berdasarkan kunci yang ditemukan dalam permintaan dan menerapkan endpoint target atau metode autentikasi kustom/eksklusif secara dinamis, dll.

Apigee menyediakan beberapa opsi bagi developer untuk menangani logika kustom tersebut. Dokumen ini akan membahas opsi tersebut dan kapan harus menggunakannya:

Kebijakan	Kasus penggunaan kebijakan
JavaScript dan PythonScript	Kapan digunakan: Kebijakan JavaScript dan PythonScript memiliki kemampuan yang setara. Pemahaman developer dalam suatu bahasa biasanya menjadi motivasi untuk memilih satu bahasa daripada bahasa lainnya. Kebijakan JavaScript dan PythonScript paling cocok untuk memproses logika inline yang tidak terlalu rumit dan tidak memerlukan penggunaan library pihak ketiga. Kebijakan ini tidak berperforma sebaik kebijakan JavaCallout. Kapan sebaiknya tidak digunakan: Gateway API Apigee bukan server aplikasi (dan juga tidak menyediakan runtime JavaScript lengkap seperti node.js). Jika callout selalu memerlukan waktu lebih dari satu detik untuk diproses, logika tersebut kemungkinan besar tidak ada di gateway 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 secara inline sangat penting. Library Java yang ada menyediakan sebagian besar logika. Kapan sebaiknya tidak digunakan: Gateway API Apigee bukan server aplikasi dan tidak dimaksudkan untuk memuat framework seperti Spring, JEE, dll. Jika callout biasanya memerlukan 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, ada batasan yang diterapkan pada jenis kode yang dapat dieksekusi. Misalnya, kode Java yang mencoba mengakses library kripto tertentu atau mengakses sistem file akan diblokir agar tidak dieksekusi. Aplikasi Java, terutama yang mengandalkan library pihak ketiga, dapat membawa banyak file JAR (dan besar). Hal ini dapat memperlambat waktu booting gateway.
ExternalCallout	Kapan digunakan: Sangat cocok untuk mengeksternalisasi logika kustom dan memungkinkan logika kustom mengakses (dan jika perlu mengubah) konteks pesan. Info eksternal menerapkan gRPC dan mungkin memiliki performa yang lebih baik daripada ServiceCallout. 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. Saat tidak digunakan: Untuk logika ringan yang dapat dieksekusi dengan cepat, inline.
ServiceCallout	Kapan digunakan: Logika yang kompleks sebaiknya diterapkan di luar gateway. Logika ini dapat memiliki siklus prosesnya sendiri (rilis dan pembuatan versi) dan tidak memengaruhi fungsi gateway. Jika 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. Saat 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 logikanya sederhana atau tidak penting, 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 ExternalCallout.
4. Jika Anda sudah memiliki implementasi eksternal dan/atau developer sudah memahami REST, gunakan ServiceCallout.

Gambar berikut menggambarkan proses ini: