Membuat proxy API dari Spesifikasi OpenAPI

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Baca dokumentasi Apigee Edge.

Yang akan Anda pelajari

Dalam tutorial ini, Anda akan mempelajari:

• Membuat proxy API Apigee dari Spesifikasi OpenAPI.
• Memanggil proxy API menggunakan cURL.
• Tambahkan kebijakan ke alur bersyarat.
• Menguji 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 mengirimkan permintaan ke layanan target tiruan Apigee.

Tentang Inisiatif Open API

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

Spesifikasi OpenAPI menggunakan format standar untuk mendeskripsikan RESTful API. Spesifikasi OpenAPI ditulis dalam format JSON atau YAML, yang dapat dibaca mesin, tetapi juga mudah dibaca dan dipahami oleh orang. Spesifikasi menjelaskan berbagai elemen API seperti jalur dasarnya, 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. Token ini tidak memerlukan kunci API atau token akses. Bahkan, Anda dapat mengaksesnya di browser web. Cobalah dengan mengklik berikut ini:

http://mocktarget.apigee.net

Layanan target menampilkan salam Hello, guest!

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

Yang 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 mengetahui 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 APIgee UI in Cloud Console: Pilih Pengembangan proxy > Proxy API.

   Jika Anda menggunakan Apigee UI 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 Create New.

   

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

   
5. Klik URL dan masukkan informasi berikut:

   OpenAPI Spec URL: 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 Select.

   Halaman Detail proxy di wizard Create Proxy akan ditampilkan. Kolom ini telah diisi otomatis menggunakan nilai yang ditentukan dalam Spesifikasi OpenAPI seperti yang ditunjukkan dalam gambar berikut:

   

   Tabel berikut menjelaskan nilai default yang telah diisi otomatis menggunakan 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 yang dapat dilihat publik dari proxy API ini terdiri dari nama domain eksternal atau internal Anda dan jalur dasar ini. Contoh: http://apitest.acme.com/mock-target-api	Konten kolom Name dikonversi ke semua huruf kecil
   Deskripsi	Deskripsi proxy API.	Properti description dari Spesifikasi OpenAPI
   Target (API yang Ada)	URL target 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 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 Common policies, di bagian Security: Authorization, pastikan Pass through (no authorization) dipilih, lalu klik Next:

   

10. Di halaman Flows, pastikan semua operasi dipilih.
    Tips: Alur bersyarat dihasilkan secara otomatis dari operasi yang ditentukan dalam objek paths di Spesifikasi OpenAPI. Alur bersyarat memberi tahu Apigee, "Saat Anda melihat ini, lakukan logika ini". Misalnya, jika panggilan API adalah GET pada resource /xml (kondisi), ubah respons ke JSON (melalui kebijakan yang terpasang pada flow kondisional). Hanya satu alur yang dijalankan per transaksi—alur pertama yang kondisinya bernilai benar.
    
11. Klik Next.
12. Di halaman Summary, pastikan lingkungan dipilih di bagian Optional Deployment lalu klik Create and deploy:

    

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

13. Klik Edit proxy untuk menampilkan halaman Overview 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 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 Menemukan nama host grup lingkungan.

Contoh:

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

Tanggapan

Anda akan melihat respons berikut:

Hello, Guest!

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

Menambahkan XML ke kebijakan 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 ini akan mengonversi respons XML target menjadi respons JSON.

Pertama, panggil API tersebut agar Anda dapat membandingkan hasilnya dengan hasil 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.

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 ke JSON. Tambahkan kebijakan XML ke JSON ke flow kondisional Respons XML Tampilan dalam proxy API.

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

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

Editor Proxy Baru

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



2. Di panel sebelah kiri, pada Endpoint Proxy > default, klik alur kondisional View XML Response.
3. Di panel kiri, klik tombol + di baris Policies.

4. Pada dialog Buat kebijakan, klik kolom Pilih jenis kebijakan, scroll ke bawah ke Mediasi, lalu pilih XMLToJSON. Pertahankan nilai default untuk Display Name dan Name.

5. Klik Create untuk membuat kebijakan.

6. Klik tombol + di samping alur View XML response dalam Response.

   

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 pada respons.

   

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

9. Klik Save.

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 > default, klik alur bersyarat View XML Response.

   

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

   

   Dialog Add Step akan terbuka untuk menampilkan daftar semua kebijakan yang dapat Anda tambahkan.

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

   
5. Pertahankan nilai default untuk Display Name dan Name.

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

   
7. Klik Save.

Setelah Anda menambahkan kebijakan, panggil API lagi menggunakan cURL. Perhatikan bahwa Anda masih memanggil resource /xml yang sama. Layanan target masih menampilkan blok XML-nya, tetapi kini kebijakan dalam proxy API akan mengonversi respons ke JSON. Buat 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 ke JSON:

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

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