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 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 untuk Flow, terutama jika nama file kebijakan tidak cukup deskriptif untuk menyatakan fungsi dasar Flow.
  • Buat komentar yang berguna. Hindari komentar yang jelas.
  • Gunakan indentasi, spasi, perataan vertikal, dan sebagainya yang konsisten.

Penulisan kode gaya framework

Pengodean 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 sehingga developer dapat menyinkronkannya dan menggunakannya di lingkungan pengembangan proxy mereka sendiri.

  • Untuk mengaktifkan DRY (jangan mengulangi diri sendiri), 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 (JavaScript, Java, XSLT) yang tidak digunakan dari proxy API, terutama resource besar yang berpotensi memperlambat prosedur impor dan deployment.

Konvensi Penamaan

  • Atribut kebijakan name dan nama file kebijakan XML harus identik.
  • Atribut name kebijakan Script dan ServiceCallout policy 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 membuat konvensi penamaan yang konsisten untuk kebijakan Anda. Misalnya, gunakan awalan pendek yang diikuti dengan urutan kata deskriptif yang dipisahkan dengan tanda hubung. Misalnya, AM-xxx untuk kebijakan AssignMessage. 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

  • Untuk mendapatkan panduan tentang desain RESTful API, download e-book Web API Design: The Missing Link.
  • Manfaatkan kebijakan dan fungsi Apigee jika memungkinkan untuk membangun proxy API. Hindari pengodean semua logika proxy di resource JavaScript, Java, atau Python.
  • Buat Alur dengan cara yang teratur. Beberapa Alur, masing-masing dengan satu kondisi, lebih baik daripada beberapa lampiran bersyarat ke PreFlow dan Postflow yang sama.
  • Sebagai 'pengaman', buat proxy API default dengan BasePath ProxyEndpoint /. Hal 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 basepath proxy API per lingkungan Apigee atau grup lingkungan. 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 RouteRule, buat satu sebagai 'default', yaitu sebagai RouteRule tanpa kondisi. Pastikan RouteRule default ditentukan terakhir dalam daftar Rute bersyarat. RouteRule dievaluasi dari atas ke bawah di ProxyEndpoint. Lihat referensi konfigurasi proxy API.
  • Ukuran paket proxy API: Ukuran paket proxy API tidak boleh lebih dari 15 MB.
  • Pembuatan versi API: Untuk mengetahui pemikiran dan rekomendasi Apigee tentang pembuatan versi API, lihat Pembuatan Versi di e-book Desain API Web: Link yang Hilang.

Mengaktifkan CORS

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

CORS (Cross-origin resource sharing) adalah mekanisme standar yang memungkinkan panggilan JavaScript XMLHttpRequest (XHR) yang dieksekusi di halaman web berinteraksi dengan resource dari domain non-asal. CORS adalah solusi yang umum diterapkan untuk kebijakan asal yang sama yang diterapkan oleh semua browser. Misalnya, jika Anda membuat panggilan XHR ke Twitter API dari kode JavaScript yang dieksekusi 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 mengetahui informasi tentang cara mengaktifkan CORS di proxy API sebelum memublikasikan API, lihat Menambahkan dukungan CORS ke proxy API.

Ukuran payload pesan

Ukuran payload pesan dalam alur permintaan atau respons untuk Apigee dibatasi secara default hingga 10 MB. Pengguna yang memerlukan pemrosesan payload besar dapat mengonfigurasi batas yang lebih tinggi menggunakan elemen <Properties> dalam konfigurasi ProxyEndpoint atau TargetEndpoint pada proxy API mereka.

Untuk mengetahui informasi selengkapnya tentang penggunaan response.payload.parse.limit atau properti request.payload.parse.limit untuk mengonfigurasi ukuran payload maksimum hingga 30 MB untuk alur permintaan atau respons, lihat Referensi konfigurasi proxy API.

Perhatikan bahwa melebihi ukuran pesan yang ditentukan akan menghasilkan error protocol.http.TooBigBody.

Pertimbangkan strategi yang direkomendasikan berikut untuk menangani ukuran pesan besar di Apigee:

  • Sebaiknya pisahkan proxy API yang sering menangani payload besar di lingkungan khusus untuk menghindari potensi skenario "tetangga berisik". Resource CPU dan memori sistem digunakan dalam jumlah yang lebih besar oleh proxy yang mengelola payload besar, terutama saat digunakan bersama dengan kebijakan yang berinteraksi dengan payload besar.
  • Sebaiknya batasi penggunaan kebijakan untuk berinteraksi dengan payload besar. Menggunakan kebijakan untuk berulang kali mengurai dan menyalin payload permintaan atau respons dapat berdampak negatif pada performa sistem.
  • Organisasi yang menangani volume besar permintaan payload tinggi dianjurkan untuk menyediakan alamat IP tambahan guna menghindari kehabisan port karena penskalaan horizontal.
  • Pertimbangkan permintaan dan respons streaming. Perhatikan bahwa saat Anda melakukan streaming, kebijakan tidak lagi memiliki akses ke konten pesan. Lihat Permintaan dan respons streaming.
  • Jika organisasi Anda menggunakan Penagihan bayar sesuai penggunaan, sebaiknya gunakan batas yang dapat dikonfigurasi untuk payload besar hanya untuk proxy API yang di-deploy di lingkungan Komprehensif.

Penanganan Fault

  • Manfaatkan FaultRules untuk menangani semua penanganan fault. (Kebijakan RaiseFault digunakan untuk menghentikan Alur pesan dan mengirim pemrosesan ke Alur FaultRules.)
  • Dalam Alur FaultRules, gunakan kebijakan AssignMessage untuk membuat respons kesalahan, bukan kebijakan RaiseFault. Menjalankan kebijakan AssignMessage secara bersyarat berdasarkan jenis kesalahan yang terjadi.
  • Selalu menyertakan pengendali kesalahan 'catch-all' default sehingga kesalahan yang dihasilkan sistem dapat dipetakan ke format respons kesalahan yang ditentukan pelanggan.
  • Jika memungkinkan, selalu buat respons error sesuai dengan format standar yang tersedia di perusahaan atau project Anda.
  • Gunakan pesan error yang bermakna dan mudah dibaca manusia yang menyarankan solusi untuk kondisi error.

Lihat Menangani kesalahan.

Persistensi

Peta Nilai/Kunci

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

Lihat kebijakan KeyValueMapOperations.

Penyimpanan dalam 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). Setelah mengambil entri responseCache, lalu konversi 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 penyiapan cache. Dalam banyak kasus, request.querystring dapat digunakan sebagai ID unik.
  • Jangan sertakan kunci API (client_id) dalam kunci cache, kecuali jika diperlukan secara eksplisit. Sering kali, API yang diamankan hanya dengan 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 kotor.
  • Jika memungkinkan, coba agar kebijakan cache respons yang mengisi cache dieksekusi di PostFlow respons ProxyEndpoint selambat mungkin. Dengan kata lain, jalankan setelah langkah-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 Anda mengambil data yang di-cache.

    Perhatikan bahwa Anda mungkin ingin menyimpan data yang tidak dimediasi dalam cache 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 caching 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 dalam proxy, ikuti panduan berikut untuk memastikan perilaku diskrit untuk setiap kebijakan:
    • Jalankan setiap kebijakan berdasarkan kondisi yang saling eksklusif. Hal ini akan membantu memastikan bahwa hanya satu dari beberapa kebijakan cache respons yang dijalankan.
    • Tentukan resource cache yang berbeda untuk setiap kebijakan cache respons. Anda menentukan resource cache dalam elemen <CacheResource> kebijakan.

Lihat kebijakan ResponseCache.

Kebijakan dan kode kustom

Kebijakan atau kode kustom?

  • Gunakan kebijakan bawaan terlebih dahulu (jika memungkinkan). Kebijakan Apigee diperkuat, dioptimalkan, dan didukung. Misalnya, gunakan kebijakan AssignMessage dan kebijakan ExtractVariables standar, bukan kebijakan JavaScript (jika memungkinkan) untuk membuat payload, mengekstrak informasi dari payload (XPath, JSONPath), dan sebagainya.
  • JavaScript lebih disukai 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).
  • Penguraian payload yang kompleks seperti melakukan iterasi melalui objek JSON dan encoding/decoding Base64.
  • Kebijakan JavaScript memiliki batas waktu, sehingga loop tak terbatas diblokir.
  • Selalu gunakan Langkah-Langkah JavaScript dan masukkan file ke folder resource jsc. Jenis kebijakan JavaScript mengompilasi kode terlebih dahulu pada waktu deployment.

Java

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

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

Python

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

Anotasi Skrip (Java, JavaScript, Python)

  • Gunakan try/catch global, atau yang setara.
  • Buat pengecualian yang bermakna dan tangkap pengecualian ini dengan benar untuk digunakan dalam respons kesalahan.
  • Tampilkan dan tangkap pengecualian lebih awal. Jangan gunakan try/catch global untuk menangani semua pengecualian.
  • Lakukan pemeriksaan null dan undefined, jika perlu. Contoh kapan harus melakukannya adalah saat mengambil variabel alur opsional.
  • Hindari membuat permintaan HTTP/S di dalam panggilan 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

  • 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 bundle dan memungkinkan file JAR lain mengakses repositori library yang sama.
  • Impor file JAR menggunakan Apigee Resources API, bukan menyertakannya di dalam folder resource proxy API. Hal ini akan mengurangi waktu deployment dan memungkinkan file JAR yang sama dirujuk oleh beberapa proxy API. Manfaat lainnya adalah isolasi pemuat class.
  • Jangan gunakan Java untuk penanganan resource (misalnya, membuat dan mengelola kumpulan thread).

Python

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

Lihat kebijakan PythonScript.

ServiceCallouts

  • Ada banyak kasus penggunaan yang valid untuk menggunakan rangkaian proxy, di mana Anda menggunakan panggilan layanan di satu proxy API untuk memanggil proxy API lain. Jika Anda menggunakan chaining proxy, pastikan untuk menghindari panggilan balik rekursif loop tak terbatas ke proxy API yang sama.

    Jika Anda menghubungkan antara proxy yang berada dalam organisasi dan lingkungan yang sama, pastikan untuk melihat Merangkai proxy API untuk mengetahui informasi selengkapnya tentang penerapan koneksi lokal yang menghindari overhead jaringan yang tidak perlu.

  • Buat pesan permintaan ServiceCallout menggunakan kebijakan AssignMessage, dan isi objek permintaan dalam variabel pesan. (Ini termasuk menyetel payload permintaan, jalur, dan metode.)
  • 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 menjaga payload pesan asli tetap utuh untuk digunakan oleh kebijakan lainnya.

Lihat kebijakan ServiceCallout.

Mengakses entitas

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. Hal ini akan menjaga format logging yang konsisten.

Lihat kebijakan MessageLogging.

Pemantauan

Pelanggan Cloud tidak diwajibkan untuk memeriksa setiap komponen Apigee (Router, Message Processor, dan sebagainya). Tim Operasi Global Apigee memantau semua komponen secara menyeluruh, bersama dengan health check API, mengingat permintaan health check oleh pelanggan.

Apigee Analytics

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

Lihat dasbor Analytics.

Debug

Alat rekaman aktivitas di UI Apigee berguna untuk men-debug masalah API runtime, selama pengembangan atau operasi produksi API.

Lihat Menggunakan alat Debug.

Keamanan

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 sebelumnya seperti memverifikasi token atau menerapkan kuota atau merespons dengan objek yang di-cache, sering kali diperlukan 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/proprietary secara dinamis, dll.

Apigee memberi developer beberapa opsi untuk menangani logika kustom tersebut. Dokumen ini akan membahas opsi tersebut dan kapan harus menggunakan opsi yang mana:

Kebijakan Kasus penggunaan kebijakan
JavaScript dan PythonScript

Kapan digunakan:

  • Kebijakan JavaScript dan PythonScript memiliki kemampuan yang setara. Keahlian developer dalam suatu bahasa biasanya menjadi motivasi untuk memilih bahasa tersebut 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 (juga tidak menyediakan runtime JavaScript lengkap seperti node.js). Jika panggilan selalu membutuhkan waktu lebih dari satu detik untuk diproses, kemungkinan besar logika tersebut tidak termasuk dalam 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 inline sangat penting.
  • Library Java yang ada menyediakan sebagian besar logika.

Kapan sebaiknya tidak digunakan:

  • Gateway API Apigee bukanlah 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 mengeksternalkan 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 memunculkan banyak file JAR (dan berukuran besar). Hal ini dapat memperlambat waktu booting gateway.
ExternalCallout

Kapan digunakan:

  • Sangat cocok untuk mengeksternalkan logika kustom dan memungkinkan logika kustom mengakses (dan jika perlu mengubah) konteks pesan.
  • Pesan 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.

Kapan tidak digunakan:

  • Untuk logika ringan yang dapat dieksekusi dengan cepat, sebaris.
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.

Kapan tidak digunakan:

  • Untuk logika ringan yang dapat dieksekusi dengan cepat, sebaris
  • 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 penerapan eksternal dan/atau developer memahami REST, gunakan ServiceCallout.

Gambar berikut menggambarkan proses ini: