Praktik terbaik untuk desain dan pengembangan proxy API dengan Apigee

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 dan TargetEndpoint. 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 dan Consumer.password.

Pengembangan proxy API

Pertimbangan Desain Awal

Peringatan: Jangan panggil Apigee API dari dalam proxy API. API 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 di alur proxy, terutama jika Anda melakukan penulisan cepat lalu baca. Solusi coding untuk perilaku ini dapat memengaruhi performa proxy Anda.

Gunakan kebijakan di proxy API sebagai gantinya.

• 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 menampilkan messaging.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.

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 pada 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 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

Peringatan: Untuk Panggilan Java, ketergantungan 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.

• 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

Peringatan: Untuk Panggilan Java, ketergantungan 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 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:
  • Kebijakan XMLThreatProtection
  • Kebijakan RegularExpressionProtection
  • Kebijakan SOAPMessageValidation

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: Kebijakan JavaScript dan PythonScript setara dalam hal kemampuan. Pemahaman developer dalam suatu bahasa biasanya menjadi motivasi untuk memilih salah satunya. Kebijakan JavaScript dan PythonScript paling cocok untuk memproses logika inline yang tidak terlalu kompleks dan tidak memerlukan penggunaan library pihak ketiga. Kebijakan ini tidak berperforma tinggi seperti kebijakan JavaCallout. Kapan tidak boleh digunakan: Gateway API Apigee bukanlah server aplikasi (juga tidak menyediakan runtime JavaScript lengkap seperti node.js). Jika info selalu membutuhkan waktu lebih dari satu detik untuk diproses, kemungkinan besar logika bukan termasuk dalam gateway dan harus menjadi bagian dari layanan yang mendasarinya. Praktik Terbaik: Apigee lebih 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 banyak logika. Kapan tidak boleh digunakan: Gateway API Apigee bukanlah server aplikasi dan tidak dimaksudkan untuk memuat framework seperti Spring, JEE, dll. Jika pemanggilan biasanya membutuhkan waktu lebih dari satu detik untuk diproses, logika dapat dianggap sebagai fungsional (logika bisnis). Pertimbangkan untuk mengeksternalkan sebagai layanan. Untuk melindungi gateway API Apigee dari penyalahgunaan, ada pembatasan yang ditempatkan pada jenis kode yang dapat dijalankan. Misalnya, kode Java yang mencoba mengakses library kripto tertentu atau mengakses sistem file akan diblokir dari eksekusi. Aplikasi Java, terutama yang mengandalkan library pihak ketiga, dapat mendatangkan banyak file JAR (dan berukuran besar). Hal ini dapat memperlambat waktu booting gateway.
ExternalCallout	Kapan digunakan: Idealnya cocok untuk mengeksternalkan logika kustom dan mengizinkan logika kustom untuk mengakses (dan jika perlu memodifikasi) 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 semacam itu. Sebagai pengganti yang efektif untuk fitur Target yang Dihosting di Apigee Edge. Jika tidak digunakan: Untuk logika ringan yang dapat dijalankan dengan cepat, secara inline.
ServiceCallout	Kapan digunakan: Logika kompleks paling baik diimplementasikan di luar gateway. Logika ini dapat memiliki siklus prosesnya sendiri (rilis dan pembuatan versi) dan tidak memengaruhi 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 dijalankan dengan cepat, secara inline Proxy API harus mentransfer konteks (seperti variabel) atau menerima konteks dari implementasi eksternal

Ringkasnya:

1. Jika logikanya sederhana atau mudah, 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 mengilustrasikan proses ini: