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:

Buat proxy Apigee API dari Spesifikasi OpenAPI.
Panggil proxy API menggunakan cURL.
Tambahkan kebijakan ke alur bersyarat.
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 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 seperti 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. API 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 ucapan Hello, guest!

Untuk mengetahui 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 dalam Ringkasan dan prasyarat.
Spesifikasi OpenAPI. Dalam tutorial ini, Anda akan menggunakan mocktarget.yaml Spesifikasi OpenAPI yang mendeskripsikan layanan target tiruan Apigee, http://mocktarget.apigee.net. Untuk mengetahui informasi selengkapnya, lihat apigee/api-platform-samples.
cURL diinstal di komputer Anda untuk melakukan panggilan API dari command line; atau browser web.

Membuat proxy API

Untuk membuat proxy API dari Spesifikasi OpenAPI:

Di konsol Google Cloud , buka halaman Apigee > Proxy development > API proxies.

Buka proxy API
Di panel API Proxies, klik + Create.
Di panel Create a proxy, di bagian Proxy template > OpenAPI spec template, pilih Reverse proxy (Most common).

Buka URL berikut di browser web Anda:

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

Klik kanan kode yang ditampilkan dan pilih Simpan Sebagai.
Klik Simpan untuk menyimpan mocktarget3.0.yaml di lokasi yang diinginkan.
Di kolom OpenAPI specs, klik tombol Browse.
Buka file mocktarget3.0.yaml, lalu klik Open.
Klik Berikutnya.
Langkah Proxy details pada wizard Create Proxy akan otomatis mengisi kolomnya dengan nilai yang diekstrak langsung dari Spesifikasi OpenAPI.

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

Kolom	Deskripsi	Default
Nama proxy	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 dapat diakses 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 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. URL apa pun yang dapat diakses melalui Internet terbuka dapat digunakan. Contoh: `http://mocktarget.apigee.net`	Properti `servers` dari Spesifikasi OpenAPI

Berikut adalah kutipan dari Spesifikasi OpenAPI yang menunjukkan 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
      ...

Pada langkah Proxy details, edit kolom Description sebagai berikut:
```
API proxy for the Apigee mock target service endpoint.
```
Klik Berikutnya.
Di langkah Alur, pastikan semua operasi dipilih.
Tips: Alur bersyarat dibuat 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, saat panggilan API adalah GET pada resource /xml (kondisi), ubah respons menjadi JSON (melalui kebijakan yang dilampirkan ke alur bersyarat). Hanya satu alur yang dijalankan per transaksi—alur pertama yang kondisinya dievaluasi sebagai benar.
Klik Berikutnya.
Pada langkah Deploy, pilih satu atau beberapa lingkungan, lalu klik OK.
Klik Create.

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 Anda.

Contoh:

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

Respons

Anda akan melihat respons berikut:

Hello, Guest!

Menambahkan kebijakan XML ke JSON

Selanjutnya, Anda akan menambahkan kebijakan XML ke JSON ke alur bersyarat 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 hasil yang diterima setelah Anda 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 ke JSON. Tambahkan kebijakan XML ke JSON ke alur bersyarat View XML Response di proxy API.

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

Pilih Lihat Respons XML

Di panel sebelah kiri, di bagian Proxy Endpoints > default, klik alur bersyarat View XML Response.
Di panel kiri, klik tombol + di baris Policies.
Dalam dialog Create policy, klik di kolom Select policy type, scroll ke bawah ke Mediation, lalu pilih XMLToJSON. Biarkan nilai default untuk Nama Tampilan dan Nama.
Klik Buat untuk membuat kebijakan.
Klik tombol + di samping alur View XML response di Response.
Dalam dialog Add Policy Step, klik di kolom Select existing policy dan pilih XML to JSON-1.
Klik Tambahkan. Kebijakan XML ke JSON diterapkan pada respons.

Untuk melihat kode alur bersyarat View XML Response, klik Switch To Code Editor.
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 kini kebijakan di proxy API akan mengonversi respons ke JSON. Lakukan panggilan ini:

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