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 mempelajari cara:

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

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

Tentang Open API Initiative

"Open API Initiative (OAI) berfokus pada pembuatan, pengembangan, dan promosi Format Deskripsi API yang netral vendor berdasarkan Spesifikasi Swagger". Untuk mengetahui informasi selengkapnya tentang Open API Initiative, lihat Spesifikasi OpenAPI.

Spesifikasi OpenAPI menggunakan format standar untuk mendeskripsikan RESTful API. Ditulis dalam format JSON atau YAML, Spesifikasi OpenAPI dapat dibaca mesin, tetapi juga mudah dibaca dan dipahami oleh manusia. Spesifikasi ini menjelaskan elemen API tersebut sebagai jalur dasar, jalur dan kata kerja, header, parameter kueri, operasi, jenis konten, deskripsi respons, dan lainnya. 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. Tidak memerlukan kunci API atau token akses. Bahkan, Anda dapat mengaksesnya di browser web. Coba dengan mengklik link berikut:

http://mocktarget.apigee.net

Layanan target menampilkan ucapan Hello, guest!

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

Yang akan Anda butuhkan

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

Membuat proxy API

Untuk membuat proxy API dari Spesifikasi OpenAPI:

1. Jika Anda menggunakan UI Apigee di konsol Cloud: Pilih Proxy development > API Proxies.

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

2. Klik API Proxies di jendela utama.

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

   

3. Klik Buat Baru.

   

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

   
5. Klik URL, lalu 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 Detail proxy di wizard Create Proxy akan ditampilkan. Kolom diisi otomatis menggunakan nilai yang ditentukan dalam Spesifikasi OpenAPI seperti yang ditunjukkan dalam gambar berikut:

   

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

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

   Berikut adalah kutipan dari Spesifikasi OpenAPI yang menunjukkan properti yang digunakan untuk mengisi otomatis kolom.

   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 Detail proxy, edit kolom Deskripsi sebagai berikut:

   API proxy for the Apigee mock target service endpoint.

8. Klik Berikutnya.
9. Di halaman Kebijakan umum, pada bagian Keamanan: Otorisasi, pastikan Pass through (tanpa otorisasi) dipilih, lalu klik Berikutnya:

   

10. Di halaman Flows, pastikan semua operasi dipilih.
    Tips: Alur kondisional dibuat secara otomatis dari operasi yang ditentukan dalam objek paths dalam Spesifikasi OpenAPI. Alur kondisional memberi tahu Apigee, "Saat Anda melihat ini, lakukan logika ini". Misalnya, jika panggilan API adalah GET pada resource /xml (kondisi), ubah respons menjadi JSON (melalui kebijakan yang dilampirkan ke alur kondisional). Hanya satu alur yang dieksekusi per transaksi—alur pertama yang kondisinya dievaluasi sebagai benar.
    
11. Klik Berikutnya.
12. Di halaman Ringkasan, pastikan lingkungan telah dipilih di bagian Deployment Opsional, lalu klik Buat dan 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 Spesifikasi OpenAPI. Selanjutnya, Anda akan mengujinya untuk melihat cara kerjanya.

Menguji proxy API

Anda dapat menguji API Mock-Target-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 Menemukan nama host grup lingkungan Anda.

Contoh:

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

Respons

Anda akan melihat respons berikut:

Hello, Guest!

Bagus! Anda telah membuat proxy API sederhana dari Spesifikasi OpenAPI dan mengujinya.

Menambahkan kebijakan XML to JSON

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

Pertama, panggil API agar Anda dapat membandingkan hasilnya dengan yang diterima setelah menambahkan kebijakan. 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 Menemukan nama host grup lingkungan.

Respons

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. Tambahkan kebijakan XML ke JSON ke alur kondisional View XML Response di proxy API.

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

Petunjuk di dua tab pertama di bawah menjelaskan cara menggunakan 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 kiri, pada bagian Proxy Endpoints > default, klik alur kondisional View XML Response.
3. Di panel kiri, klik tombol + di baris Policies.

4. Pada dialog Create policy, klik kolom Select policy type, scroll ke bawah ke Mediation, lalu pilih XMLToJSON. Biarkan nilai default untuk Nama Tampilan dan Nama.

5. Klik Create untuk membuat kebijakan.

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

   

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

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

   

   Untuk melihat kode alur kondisional View XML Response, klik Switch To Code Editor.

9. Klik Simpan.

Editor Proxy Klasik

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

   

2. Di panel Navigator kiri, pada bagian Proxy Endpoints > default, klik alur kondisional View XML Response.

   

3. Klik tombol +Langkah di bagian bawah, yang sesuai dengan Respons untuk alur.

   

   Dialog Tambahkan Langkah akan terbuka untuk menampilkan daftar yang dikategorikan dari semua kebijakan yang dapat Anda tambah.

4. Scroll ke kategori Mediasi, lalu pilih XML to JSON.

   
5. Biarkan nilai default untuk Nama Tampilan dan Nama.

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

   
7. Klik Simpan.

Setelah menambahkan kebijakan, panggil API lagi menggunakan cURL. Perhatikan bahwa Anda masih memanggil resource /xml yang sama. Layanan target masih menampilkan blok XML-nya, tetapi sekarang kebijakan di proxy API akan mengonversi respons menjadi JSON. Lakukan panggilan ini:

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

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

Perhatikan bahwa respons XML dikonversi menjadi JSON:

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

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