Membuat proxy API dari Spesifikasi OpenAPI

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat Dokumentasi Apigee Edge.

Yang akan Anda pelajari

Dalam tutorial ini, Anda akan belajar:

• Buat proxy Apigee API dari Spesifikasi OpenAPI.
• Memanggil proxy API menggunakan cURL.
• Menambahkan kebijakan ke alur kondisional.
• Uji pemanggilan kebijakan menggunakan cURL.

Anda akan mempelajari cara membuat proxy Apigee API dari OpenAPI Spesifikasi menggunakan UI Apigee. Saat Anda memanggil proxy API dengan Klien HTTP, seperti cURL, proxy API mengirimkan permintaan ke target tiruan Apigee layanan.

Tentang Open API Initiative

"Open API Initiative (OAI) difokuskan pada membuat, mengembangkan, dan mempromosikan Format Deskripsi API yang tidak terikat dengan vendor berdasarkan Swagger Spesifikasi". Untuk informasi selengkapnya tentang Inisiatif Open API, lihat Spesifikasi OpenAPI.

Spesifikasi OpenAPI menggunakan format standar untuk mendeskripsikan RESTful API. Ditulis dalam format JSON atau YAML, Spesifikasi OpenAPI dapat dibaca oleh mesin, tetapi juga mudah dibaca dan dipahami oleh manusia. Spesifikasi menjelaskan elemen seperti API sebagai jalur dasar, jalur dan kata kerja, header, parameter kueri, operasi, jenis konten, deskripsi respons, dan lain-lain. Selain itu, Spesifikasi OpenAPI biasanya digunakan untuk membuat dokumentasi API.

Tentang layanan target tiruan Apigee

Layanan target tiruan Apigee yang digunakan dalam tutorial ini dihosting di Apigee dan menampilkan data sederhana. Pengujian ini tidak memerlukan kunci API atau token akses. Bahkan, Anda dapat mengaksesnya di web browser. Cobalah dengan mengklik yang berikut ini:

http://mocktarget.apigee.net

Layanan target akan menampilkan Hello, guest! ucapan

Untuk informasi tentang kumpulan API lengkap yang didukung layanan target tiruan, lihat API Contoh Apigee

Yang akan Anda butuhkan

• Sebelum memulai, Anda harus menyelesaikan langkah-langkah dalam Ringkasan dan prasyarat.
• Spesifikasi OpenAPI. Dalam tutorial ini, Anda akan menggunakan mocktarget.yaml Spesifikasi OpenAPI yang menjelaskan target tiruan Apigee layanan, http://mocktarget.apigee.net. Untuk informasi selengkapnya, lihat apigee/api-platform-samples.
• cURL yang diinstal di komputer Anda untuk melakukan panggilan API dari baris perintah; atau {i>browser<i} web.

Membuat proxy API

Untuk membuat proxy API dari Spesifikasi OpenAPI:

1. Jika Anda menggunakan UI Apigee di Konsol Cloud: Pilih Pengembangan proxy > Proxy API.

   Jika Anda menggunakan UI Apigee klasik: Pilih Develop > Proxy API dan di panel Proxies, pilih lingkungan untuk proxy.

2. Klik Proxy API di jendela utama.

   Atau, Anda dapat memilih Develop > Proxy API di menu navigasi sebelah kiri.

   

3. Klik Create New.

   

4. Di wizard Create Proxy, klik Use OpenAPI Spec untuk template Reverse proxy (paling umum).

   
5. Klik URL dan masukkan informasi berikut:

   URL Spesifikasi OpenAPI: Jalur ke konten mentah di GitHub untuk Spesifikasi OpenAPI di kolom URL:

   https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml

6. Klik Pilih.

   Halaman Proxy details di wizard Create Proxy akan ditampilkan. Kolom telah diisi sebelumnya menggunakan nilai yang ditentukan dalam Spesifikasi OpenAPI seperti ditunjukkan dalam gambar berikut:

   

   Tabel berikut menjelaskan nilai default yang telah diisi otomatis menggunakan atribut Spesifikasi OpenAPI:

   Kolom	Deskripsi	Default
   Nama	Nama proxy API. Misalnya: Mock-Target-API.	Properti title dari Spesifikasi OpenAPI dengan spasi yang diganti dengan tanda hubung
   Jalur dasar	Komponen jalur yang mengidentifikasi proxy API ini secara unik dalam organisasi. URL proxy API ini yang ditampilkan ke publik terdiri dari resource eksternal atau internal nama domain dan jalur dasar ini. Contoh: http://apitest.acme.com/mock-target-api	Konten kolom Name dikonversi menjadi huruf kecil semua
   Deskripsi	Deskripsi proxy API.	Properti description dari Spesifikasi OpenAPI
   Target (API yang Sudah Ada)	URL target yang dipanggil atas nama proxy API ini. Setiap URL yang dapat diakses melalui internet terbuka dapat digunakan. Contoh: http://mocktarget.apigee.net	Properti servers dari Spesifikasi OpenAPI

   Berikut ini adalah kutipan dari Spesifikasi OpenAPI yang menampilkan properti yang digunakan untuk mengisi kolom secara otomatis.

   openapi: 3.0.0
   info:
     description: OpenAPI Specification for the Apigee mock target service endpoint.
     version: 1.0.0
     title: Mock Target API
   paths:
     /:
       get:
         summary: View personalized greeting
         operationId: View a personalized greeting
         description: View a personalized greeting for the specified or guest user.
         parameters:
           - name: user
             in: query
             description: Your user name.
             required: false
             schema:
               type: string
         responses:
           "200":
             description: Success
   ...
   servers:
     - url: http://mocktarget.apigee.net
     - url: https://mocktarget.apigee.net
   ...
   

7. Di halaman Proxy details, edit kolom Description sebagai berikut:

   API proxy for the Apigee mock target service endpoint.

8. Klik Next.
9. Di halaman Kebijakan umum, di bagian Keamanan: Otorisasi pastikan bahwa Lulus (tanpa otorisasi) dipilih, lalu klik Berikutnya:

   

10. Di halaman Flows, pastikan semua operasi dipilih.
    Tips: Alur bersyarat dibuat secara otomatis dari operasi yang ditentukan dalam objek paths di OpenAPI Spesifikasi. Alur bersyarat memberi tahu Apigee, "Saat Anda melihat ini, jalankan logika ini". Misalnya, saat panggilan API adalah GET pada resource /xml (kondisi), mengubah respons ke JSON (melalui kebijakan yang terlampir pada alur bersyarat). Hanya satu alur yang dieksekusi per transaksi—alur pertama yang kondisi tersebut bernilai benar (true).
    
11. Klik Next.
12. Di halaman Ringkasan, pastikan lingkungan sudah dipilih di bawah Deployment Opsional lalu klik Create and deploy:

    

    Apigee membuat proxy API baru dan men-deploy-nya ke lingkungan Anda:

13. Klik Edit proxy untuk menampilkan halaman Ringkasan untuk proxy API.

Selamat! Anda telah membuat proxy API dari OpenAPI Spesifikasi. Berikutnya, Anda akan mengujinya untuk melihat cara kerjanya.

Menguji proxy API

Anda dapat menguji Mock-Target-API API menggunakan cURL atau browser web.

curl -v YOUR_ENV_GROUP_HOSTNAME/myproxy

dengan YOUR_ENV_GROUP_HOSTNAME adalah nama host grup lingkungan Anda. Lihat Temukan nama host grup lingkungan Anda.

Contoh:

curl -v -k https://apitest.acme.com/myproxy

Tanggapan

Anda akan melihat respons berikut:

Hello, Guest!

Kerja yang bagus! Anda telah membangun proxy API sederhana dari Spesifikasi OpenAPI dan menguji API tersebut.

Menambahkan XML ke kebijakan JSON

Selanjutnya, Anda akan menambahkan kebijakan XML ke JSON ke View XML Response alur bersyarat yang dibuat secara otomatis saat Anda membuat proxy API dari Spesifikasi OpenAPI. Kebijakan ini akan mengonversi respons XML target menjadi JSON yang dihasilkan.

Pertama, panggil API agar Anda dapat membandingkan hasil dengan hasil yang diterima setelah menambahkan kebijakan tersebut. Di jendela terminal, jalankan perintah cURL berikut. Anda memanggil resource /xml layanan target, yang secara native menampilkan blok XML sederhana.

curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml

dengan YOUR ENV_GROUP_HOSTNAME adalah nama host grup lingkungan. Lihat Temukan nama host grup lingkungan.

Tanggapan

Anda akan melihat respons berikut:

<root> 
  <city>San Jose</city> 
  <firstName>John</firstName> 
  <lastName>Doe</lastName> 
  <state>CA</state> 
</root>

Sekarang mari kita lakukan sesuatu yang mengonversi respons XML menjadi JSON. Menambahkan kebijakan XML ke JSON ke alur bersyarat View XML Response dalam proxy API.

Catatan: Apigee memperkenalkan Proxy versi baru Editor, yang akan mempermudah pengelolaan proxy.

Petunjuk pada dua tab pertama di bawah ini menjelaskan cara gunakan Editor Proxy baru atau Editor Proxy klasik.

Editor Proxy Baru

1. Klik tab Develop di halaman Mock-Target-API Overview di UI Apigee.



2. Di panel sebelah kiri, pada Proxy Endpoints > secara default, klik tombol View Respons XML.
3. Di panel sebelah kiri, klik tombol + di baris Policies.

4. Pada dialog Create policy, klik kolom Select policy type, scroll ke bawah ke Mediasi, lalu pilih XMLToJSON. Simpan nilai default untuk Display Name dan Name.

5. Klik Create untuk membuat kebijakan.

6. Klik tombol + di samping alur Lihat respons XML di Respons.

   

7. Pada dialog Add Policy Step, klik Select existing policy dan pilih XML to JSON-1.

8. Klik Tambahkan. Kebijakan XML ke JSON diterapkan pada respons.

   

   Guna melihat kode untuk alur bersyarat View XML Response, klik Beralih ke Editor Kode.

9. Klik Simpan.

Editor Proxy Klasik

1. Klik tab Develop di halaman Mock-Target-API Overview di UI Apigee.

   

2. Di panel Navigator sebelah kiri, di bagian Proxy Endpoints > secara default, klik tombol View Respons XML.

   

3. Klik tombol +Step bawah, yang sesuai dengan Respons untuk alur.

   

   Dialog Tambahkan Langkah akan terbuka untuk menampilkan daftar kategori semua kebijakan yang dapat Anda tambahkan.

4. Scroll ke kategori Mediasi dan pilih XML ke JSON.

   
5. Simpan nilai default untuk Display Name dan Name.

6. Klik Tambahkan. Kebijakan XML ke JSON diterapkan pada respons.

   
7. Klik Simpan.

Setelah menambahkan kebijakan, panggil API lagi menggunakan cURL. Perhatikan bahwa Anda masih memanggil resource /xml yang sama. Layanan target masih mengembalikan bloknya XML, tetapi sekarang kebijakan di proxy API akan mengonversi respons ke JSON. Buat ini hubungi:

curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml

dengan YOUR ENV_GROUP_HOSTNAME adalah nama host grup lingkungan. Lihat Temukan nama host grup lingkungan.

Perhatikan bahwa respons XML dikonversi ke JSON:

{"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}

Selamat! Anda telah berhasil menguji eksekusi kebijakan yang ditambahkan ke alur bersyarat.