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 API Apigee dari Spesifikasi OpenAPI.
  • Panggil proxy API menggunakan cURL.
  • Menambahkan 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

Inisiatif Open API

"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. 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 Apigee Sample APIs

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:

Apigee di Konsol Cloud

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

    Buka proxy API

  2. Di panel API Proxies, klik + Create.
  3. Di panel Create a proxy, di bagian Proxy template > OpenAPI spec template, pilih Reverse proxy (Most common).
  4. Buka URL berikut di browser web Anda:
    https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
  5. Klik kanan kode yang ditampilkan dan pilih Simpan Sebagai.
  6. Klik Simpan untuk menyimpan mocktarget3.0.yaml di lokasi yang diinginkan.
  7. Di kolom OpenAPI specs, klik tombol Browse.
  8. Buka file mocktarget3.0.yaml, lalu klik Open.
  9. Klik Berikutnya.
  10. Langkah Proxy details pada wizard Create Proxy akan otomatis mengisi kolomnya dengan nilai yang diekstrak langsung dari Spesifikasi OpenAPI.
  11. 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
          ...
          
  12. Di langkah Detail proxy, edit kolom Deskripsi sebagai berikut:
    API proxy for the Apigee mock target service endpoint.
  13. Klik Berikutnya.
  14. Di langkah Alur, pastikan semua operasi dipilih.
  15. Klik Berikutnya.
  16. Pada langkah Deploy, pilih satu atau beberapa lingkungan, lalu klik OK.
  17. Klik Buat.

UI Apigee Klasik

  1. 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 panel navigasi sebelah kiri.

    Klik API Proxies di halaman landing

  3. Klik Buat Baru.

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

    Membangun jenis Proxy
  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 Proxy details di wizard Create Proxy akan ditampilkan. Kolom sudah diisi otomatis menggunakan nilai yang ditentukan dalam Spesifikasi OpenAPI seperti yang ditunjukkan pada gambar berikut:

    Tabel berikut menjelaskan nilai default yang telah diisi sebelumnya 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 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
    ...
    
  7. Di halaman Proxy details, edit kolom Description sebagai berikut:
    API proxy for the Apigee mock target service endpoint.
  8. Klik Berikutnya.
  9. Di halaman Common policies, pada bagian Security: Authorization, pastikan Pass through (no authorization) dipilih, lalu klik Next:

    Pass through (tanpa otorisasi) dipilih di halaman Kebijakan umum

  10. Di halaman Flows, pastikan semua operasi dipilih. Membangun Alur Proxy
  11. Klik Berikutnya.
  12. Di halaman Ringkasan, pastikan lingkungan dipilih di bagian Deployment Opsional, lalu klik Buat dan deploy:

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

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

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

Apigee di Konsol Cloud

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

  2. Pilih Lihat Respons XML

  3. Di panel kiri, di bagian Proxy Endpoints > default, klik alur bersyarat View XML Response.
  4. Di panel sebelah kiri, klik tombol + di baris Kebijakan.
  5. Pada 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.

  6. Klik Buat untuk membuat kebijakan.
  7. Klik tombol + di samping alur View XML response di Response.

    Pilih +Langkah

  8. Dalam dialog Add Policy Step, klik di kolom Select existing policy dan pilih XML to JSON-1.
  9. Klik Tambahkan. Kebijakan XML ke JSON diterapkan pada respons.

    Kebijakan XML ke JSON dalam alur

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

  10. Klik Simpan.

UI Apigee Klasik

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

    Tab Developer
  2. Di panel Navigator kiri, di bagian Proxy Endpoints > default, klik alur bersyarat View XML Response.

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

    Pilih +Langkah

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

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

    Dialog Tambahkan Langkah
  5. Biarkan nilai default untuk Nama Tampilan dan Nama.
  6. Klik Tambahkan. Kebijakan XML ke JSON diterapkan pada respons.

    Kebijakan XML ke JSON dalam alur
  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 kini 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"}}