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

Selain pedoman di sini, postingan Komunitas Apigee Edge Antipatterns mungkin juga bermanfaat.

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 mengekspresikan fungsi yang mendasari Flow.
  • Jadikan komentar bermanfaat. Hindari komentar yang vulgar.
  • Gunakan indentasi, spasi, perataan vertikal yang konsisten, dll.

Coding bergaya framework

Coding bergaya 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 dalam 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 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 Anda dan ditambahkan ke setiap proxy API yang perlu mengekstrak parameter atau menetapkan header CORS, tanpa mengharuskan Anda membuat konfigurasi redundan (dan karenanya kurang mudah 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 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 fungsinya. Apigee merekomendasikan agar Anda menetapkan konvensi penamaan yang konsisten untuk kebijakan Anda. Misalnya, gunakan awalan pendek yang diikuti serangkaian kata deskriptif yang dipisahkan dengan tanda hubung. Misalnya, AM-xxx untuk kebijakan ReplaceMessage. 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 panduan tentang desain RESTful API, download e-book Desain Web API: Link yang Hilang.
  • Manfaatkan kebijakan dan fungsionalitas Apigee Edge untuk membuat proxy API jika memungkinkan. Hindari coding semua logika proxy di resource JavaScript, Java, atau Python.
  • Membangun Flow secara terorganisir. Beberapa Alur, masing-masing dengan satu kondisi, lebih disarankan daripada beberapa lampiran bersyarat pada PreFlow dan Postflow yang sama.
  • Sebagai 'failsafe', buat proxy API default dengan ProxyEndpoint BasePath sebesar /. Parameter 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 aturan sebagai 'default', yaitu, sebagai RouteRule tanpa kondisi. Pastikan RouteRule default ditentukan terakhir dalam daftar Routes 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. 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 Pembuatan Versi di e-book Desain API Web: Link yang Tidak Ada.

Mengaktifkan CORS

Sebelum memublikasikan API, Anda harus mengaktifkan CORS pada proxy API 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, panggilan akan gagal. Hal ini dikarenakan domain yang menayangkan halaman ke browser Anda tidak sama dengan domain yang menayangkan Twitter API. CORS menyediakan solusi untuk masalah ini dengan mengizinkan server untuk "memilih ikut serta" jika ingin menyediakan berbagi resource lintas asal.

Untuk informasi tentang cara mengaktifkan CORS pada proxy API Anda 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 menghasilkan error protocol.http.TooBigBody.

Masalah ini juga dibahas dalam postingan Komunitas Apigee ini.

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

  • Streaming permintaan dan respons. Perlu diperhatikan 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 dalam parameter HTTPResponse.body.buffer.limit. Pastikan untuk melakukan pengujian sebelum men-deploy perubahan ke produksi.
  • Di Edge untuk 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 untuk 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 pada Router atau Pemroses Pesan 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 Kesalahan

  • Memanfaatkan FaultRules untuk menangani semua penanganan fault. (Kebijakan RaiseFault digunakan untuk menghentikan Alur pesan dan mengirim pemrosesan ke Alur FaultRules.)
  • Dalam Alur FaultRules, gunakan kebijakan ProvideMessage 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 bermakna yang dapat dibaca manusia yang menyarankan solusi untuk kondisi error.

Lihat Menangani kesalahan.

Untuk praktik terbaik industri, lihat desain respons error RESTful.

Persistensi

Peta Kunci/Nilai

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

Lihat Kebijakan Map Operations Nilai Kunci.

Menyimpan ke 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 dua kali, tiga kali lipat, atau lebih.
  • Pastikan kunci cache cukup untuk memenuhi persyaratan cache. Dalam banyak kasus, request.querystring dapat digunakan sebagai ID unik.
  • Jangan menyertakan 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 ke semua klien untuk permintaan tertentu. Tidak efisien untuk menyimpan nilai yang sama untuk sejumlah entri berdasarkan kunci API.
  • Setel interval habis masa berlaku cache yang sesuai untuk menghindari pembacaan yang kotor.
  • Jika memungkinkan, cobalah untuk memiliki kebijakan cache respons yang mengisi cache yang dieksekusi pada PostFlow respons ProxyEndpoint selambat mungkin. Dengan kata lain, buat agar eksekusi berjalan setelah 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.

    Perlu diperhatikan bahwa sebaiknya Anda menyimpan data yang belum dimediasi dalam cache jika mediasi menghasilkan respons yang berbeda dari setiap 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 populasi cache respons sedekat mungkin dengan respons klien.
  • Saat menggunakan beberapa kebijakan cache respons yang berbeda dalam proxy, ikuti panduan berikut untuk memastikan perilaku yang berlainan untuk setiap kebijakan:
    • Menjalankan setiap kebijakan berdasarkan kondisi yang sama-sama bersifat 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 Cache Respons.

Kebijakan dan kode kustom

Kebijakan atau kode kustom?

  • Gunakan kebijakan bawaan terlebih dahulu dan utama (jika memungkinkan). Kebijakan Apigee diperkuat, dioptimalkan, dan didukung. Misalnya, gunakan kebijakan standar MenetapkanMessage dan ExtractVariables, bukan JavaScript (jika memungkinkan) untuk membuat payload, mengekstrak informasi dari payload (XPath, JSONPath), dll.
  • JavaScript lebih diutamakan daripada Python dan Java. Namun, jika performa adalah 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 JavaScript Steps dan masukkan file dalam folder resource jsc. Jenis Kebijakan JavaScript mengompilasi kode pada waktu deployment terlebih dahulu.

Lihat proxy Pemrograman API dengan JavaScript.

Java

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

Lihat Mengonversi respons ke huruf besar dengan info Java dan Kebijakan pemanggilan Java untuk informasi tentang penggunaan Java di proxy API.

Python

  • Jangan gunakan Python kecuali benar-benar diperlukan. Skrip Python dapat menimbulkan bottleneck performa untuk eksekusi sederhana, karena 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.
  • Tampilkan 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 flow opsional.
  • Hindari membuat permintaan HTTP/S di dalam info skrip. Sebagai gantinya, gunakan kebijakan Apigee ServiceCallout karena kebijakan tersebut 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 mengurangi ukuran paket dan akan 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).

Lihat Mengonversi respons ke huruf besar dengan info Java.

Python

  • Menampilkan pengecualian yang berarti dan menangkapnya dengan benar untuk digunakan dalam respons kesalahan Apigee

Lihat kebijakan Skrip Python.

ServiceCallouts

  • Ada banyak kasus penggunaan yang valid dalam menggunakan perantaian proxy, ketika Anda menggunakan pemanggilan layanan di satu proxy API untuk memanggil proxy API lainnya. Jika Anda menggunakan perantaian proxy, pastikan untuk menghindari pemanggilan rekursif "limited loop" kembali ke proxy API yang sama.

    Jika Anda terhubung antara proxy yang berada di organisasi dan lingkungan yang sama, pastikan untuk melihat Chaining API proxy secara bersamaan untuk mengetahui informasi selengkapnya tentang cara menerapkan koneksi lokal untuk menghindari overhead jaringan yang tidak perlu.

  • Buat pesan permintaan ServiceCallout menggunakan kebijakan ProvideMessage, dan isi objek permintaan dalam variabel pesan. (Hal ini termasuk penetapan payload, jalur, dan metode permintaan.)
  • URL yang dikonfigurasi dalam kebijakan memerlukan spesifikasi protokol, yang berarti bagian protokol URL, https:// misalnya, tidak dapat ditentukan oleh variabel. Selain itu, Anda harus menggunakan variabel terpisah untuk bagian domain pada URL dan untuk bagian URL lainnya. Misalnya: https://{domain}/{path}.
  • 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 Panggilan Layanan.

Mengakses entitas

Kebijakan AccessEntity

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

Lihat Kebijakan Entitas Akses.

Logging

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

Lihat kebijakan MessageLogging.

Monitoring

Pelanggan cloud tidak diwajibkan untuk memeriksa komponen Apigee Edge secara terpisah (Router, Message Processors, dll.). Tim Operasi Global Apigee memantau semua komponen secara menyeluruh, beserta health check API, berdasarkan permintaan health check oleh pelanggan.

Analisis Apigee

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

Lihat dasbor Analytics.

Rekaman aktivitas

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

Lihat Menggunakan alat Trace.

Keamanan