Praktik terbaik untuk desain dan pengembangan proxy API

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X. info

Tujuan dokumen ini adalah untuk memberikan serangkaian standar dan praktik terbaik untuk pengembangan dengan Apigee Edge. 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 postingan Komunitas Antipola Apigee Edge 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, dll. 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 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. Kebijakan khusus untuk memasukkan header CORS dapat disebut AssignMessage.SetCORSHeaders. Kebijakan tersebut kemudian dapat disimpan di sistem kontrol sumber dan ditambahkan ke setiap proxy API yang perlu mengekstrak parameter atau menetapkan header CORS, tanpa mengharuskan Anda membuat konfigurasi yang redundan (dan lebih sedikit dapat dikelola).
  • Bersihkan kebijakan dan resource yang tidak digunakan (JavaScript, Java, XSLT, dll.) dari proxy API, terutama resource besar yang berpotensi memperlambat prosedur impor dan deployment.

Konvensi Penamaan

  • Atribut name Kebijakan dan nama file kebijakan XML harus identik.
  • Atribut name kebijakan Script dan 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 oleh 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

  • Untuk panduan desain RESTful API, download eBook Desain API Web: Link yang Hilang.
  • Manfaatkan kebijakan dan fungsi Apigee Edge 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.
  • 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. Di Apigee Edge untuk Private Cloud, Anda dapat mengubah batasan ukuran dengan mengubah properti thrift_framed_transport_size_in_mb di lokasi berikut: cassandra.yaml (di Cassandra) dan conf/apigee/management-server/repository.properties.
  • Pembuatan versi API: Untuk mengetahui pendapat dan rekomendasi Apigee tentang pembuatan versi API, lihat bagian Pembuatan Versi di e-book Desain API Web: The Missing Link.

Mengaktifkan CORS

Sebelum memublikasikan API, Anda harus mengaktifkan CORS di proxy API 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 mereka ingin menyediakan cross-origin resource sharing.

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

Ukuran payload pesan

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

Masalah ini juga dibahas dalam postingan Komunitas Apigee ini.

Berikut adalah strategi yang direkomendasikan untuk menangani ukuran pesan yang besar di Edge:

  • Streaming permintaan dan respons. Perhatikan bahwa saat Anda melakukan streaming, kebijakan tidak lagi memiliki akses ke konten pesan. Lihat Permintaan dan respons streaming.
  • Di Edge untuk Private Cloud versi 4.15.07 dan yang lebih lama, edit file http.properties pemroses pesan untuk meningkatkan batas di parameter HTTPResponse.body.buffer.limit. Pastikan untuk menguji sebelum men-deploy perubahan ke produksi.
  • Di Edge for Private Cloud versi 4.16.01 dan yang lebih baru, permintaan dengan payload harus menyertakan header Content-Length, atau jika melakukan streaming, header "Transfer-Encoding: chunked". Untuk POST ke proxy API dengan payload kosong, Anda harus meneruskan Content-Length 0.
  • Di Edge for Private Cloud versi 4.16.01 dan yang lebih baru, tetapkan properti berikut di /opt/apigee/router.properties atau message-processor.properties untuk mengubah batas. Lihat Menetapkan batas ukuran pesan di Router atau Message Processor untuk mengetahui informasi selengkapnya.

    Kedua properti memiliki nilai default "10m" yang sesuai dengan 10 MB:
    • conf_http_HTTPRequest.body.buffer.limit
    • conf_http_HTTPResponse.body.buffer.limit

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 agar 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.

Untuk praktik terbaik industri, lihat desain respons error RESTful.

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 Operasi Peta Nilai Kunci.

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 diperlukan secara eksplisit. 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. Hal 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 dalam elemen <CacheResource> kebijakan.

Lihat Kebijakan Cache Respons.

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 dan ExtractVariables standar, bukan JavaScript (jika memungkinkan) untuk membuat payload, mengekstrak informasi dari payload (XPath, JSONPath), dll.
  • 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 berbagai kombinasi URI).
  • 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.

Lihat Memprogram proxy API dengan JavaScript.

Java

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

Lihat Mengonversi respons menjadi huruf besar dengan info Java dan kebijakan Info Java untuk 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 Apigee 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 Edge 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 dirujuk oleh beberapa proxy API. Manfaat lainnya adalah isolasi loader class.
  • Jangan gunakan Java untuk penanganan resource (misalnya, membuat dan mengelola kumpulan thread).

Lihat Mengonversi respons menjadi huruf besar dengan info Java.

Python

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

Lihat kebijakan Skrip Python.

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 tanpa batas" kembali ke proxy API yang sama.

    Jika Anda menghubungkan antar-proxy yang berada di 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. Misalnya: https://{domain}/{path}.
  • Simpan objek respons untuk ServiceCallout dalam variabel pesan terpisah. Kemudian, Anda dapat menafsirkan variabel pesan dan mempertahankan payload pesan asli agar dapat digunakan oleh kebijakan lain.

Lihat kebijakan Pemberitahuan Layanan.

Mengakses entity

Kebijakan AccessEntity

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

Lihat Kebijakan Entitas Akses.

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 Edge (Router, Message Processor, dll.). Tim Global Operations Apigee memantau semua komponen secara menyeluruh, beserta health check API, berdasarkan permintaan health check oleh pelanggan.

Apigee Analytics

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

Lihat Dasbor Analytics.

Trace

Alat pelacakan di UI pengelolaan Edge API berguna untuk men-debug masalah API runtime, selama operasi pengembangan atau produksi API.

Lihat Menggunakan alat Trace.

Keamanan