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 dari pengalaman developer yang bekerja dengan Apigee untuk menerapkan program API yang berhasil. Dokumen ini adalah dokumen aktif dan akan diperbarui dari waktu ke waktu.

Selain pedoman 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 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, dll. 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 dalam 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. Kebijakan khusus untuk menyisipkan header CORS dapat disebut AssignMessage.SetCORSHeaders. Kebijakan tersebut kemudian dapat disimpan dalam sistem kontrol sumber Anda dan ditambahkan ke setiap proxy API yang perlu mengekstrak parameter atau menetapkan header CORS, tanpa mengharuskan Anda membuat konfigurasi yang berlebihan (dan oleh karena itu kurang dapat dikelola).
  • Hapus 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 Kebijakan name dan nama file kebijakan XML harus sama.
  • Atribut name kebijakan Script dan ServiceCallout serta nama file resource harus sama.
  • DisplayName harus secara akurat menjelaskan fungsi kebijakan 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 Edge jika memungkinkan untuk membangun proxy API. Hindari pengodean semua logika proxy di resource JavaScript, Java, atau Python.
  • Buat Alur secara 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.
  • 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: 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 pemikiran dan rekomendasi Apigee tentang pembuatan versi API, lihat bagian Pembuatan versi dalam e-book Web API Design: 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 JavaScript XMLHttpRequest (XHR) yang dieksekusi di halaman web berinteraksi dengan resource dari domain lintas origin. CORS adalah solusi yang umum diterapkan untuk kebijakan origin 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

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:

  • Permintaan dan respons streaming. 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 message processor untuk meningkatkan batas dalam parameter HTTPResponse.body.buffer.limit. Pastikan untuk menguji 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 dalam kasus 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 di 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

  • Manfaatkan FaultRules untuk menangani semua penanganan gangguan. (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. Jalankan 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 kesalahan 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.

Untuk mengetahui praktik terbaik industri, lihat Desain respons error RESTful.

Persistensi

Peta Kunci/Nilai

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

Lihat Kebijakan Operasi Peta Key Value.

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 caching. Dalam banyak kasus, request.querystring dapat digunakan sebagai ID unik.
  • Jangan sertakan kunci API (client_id) dalam kunci cache, kecuali jika diperlukan secara eksplisit. Biasanya, 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 buat kebijakan cache respons yang mengisi cache dieksekusi di PostFlow respons ProxyEndpoint sesegera mungkin. Dengan kata lain, minta agar dijalankan 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 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 penerapan 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 Cache Respons.

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 ExtractVariables standar, bukan JavaScript (jika memungkinkan) untuk membuat payload, mengekstrak informasi dari payload (XPath, JSONPath), dll.
  • 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 pada objek JSON dan encoding/decoding Base64.
  • Kebijakan JavaScript memiliki batas waktu, sehingga loop tanpa batas akan diblokir.
  • Selalu gunakan Langkah-Langkah JavaScript dan masukkan file ke 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.
  • Sertakan file sumber Java dalam pelacakan kode sumber.

Lihat Mengonversi respons menjadi huruf besar dengan panggilan Java dan kebijakan Panggilan Java untuk 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.

Panggilan 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 Apigee 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 Edge 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 kelas.
  • Jangan gunakan Java untuk penanganan resource (misalnya, membuat dan mengelola kumpulan thread).

Lihat Mengonversi respons menjadi huruf besar dengan panggilan Java.

Python

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

Lihat kebijakan Skrip Python.

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 lebih lanjut 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. (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. Misalnya: https://{domain}/{path}.
  • 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 Service Callout.

Mengakses entitas

Kebijakan AccessEntity

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

Lihat Kebijakan Entitas Akses.

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

Apigee Analytics

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

Lihat dasbor Analytics.

Trace

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