Membuat proxy API dari Spesifikasi OpenAPI

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X. info

Yang akan Anda pelajari

Dalam tutorial ini, Anda akan mempelajari cara:

  • Membuat proxy Edge API dari Spesifikasi OpenAPI.
  • Memanggil proxy API menggunakan cURL.
  • Tambahkan kebijakan ke alur bersyarat.
  • Uji pemanggilan kebijakan menggunakan cURL.

Dalam tutorial ini, Anda akan mempelajari cara membuat proxy Edge API dari Spesifikasi OpenAPI menggunakan UI pengelolaan Apigee Edge. Saat Anda memanggil proxy API dengan klien HTTP, seperti cURL, proxy API akan mengirimkan permintaan ke layanan target tiruan Apigee.

Tentang Inisiatif Open API

Inisiatif Open API
"Open API Initiative (OAI) berfokus untuk membuat, mengembangkan, dan mempromosikan Format Deskripsi API yang tidak bergantung pada vendor berdasarkan Spesifikasi Swagger." Untuk informasi lebih lanjut tentang Open API Initiative, lihat https://openapis.org.

Spesifikasi OpenAPI menggunakan format standar untuk mendeskripsikan API RESTful. Ditulis dalam format JSON atau YAML, Spesifikasi OpenAPI dapat dibaca oleh mesin, tetapi juga mudah dibaca dan dipahami oleh manusia. Spesifikasi menjelaskan elemen-elemen API seperti 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. Metode 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 akan menampilkan salam Hello, guest!

Untuk informasi tentang set lengkap API yang didukung layanan target tiruan, klik berikut ini:

http://mocktarget.apigee.net/help

Yang akan Anda butuhkan

  • Akun Apigee Edge. Jika belum memiliki akun, Anda dapat mendaftar dengan mengikuti petunjuk di Membuat akun Apigee Edge.
  • 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 https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.
  • cURL yang diinstal di komputer Anda untuk melakukan panggilan API dari command line; atau browser web.

Membuat proxy API

Edge

Untuk membuat proxy API dari Spesifikasi OpenAPI menggunakan Edge UI:

  1. Login ke https://apigee.com/edge.
  2. Klik Proxy API di jendela utama.

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

    Klik Proxy API di halaman landing

  3. Klik + Proxy.
    Tambahkan proxy API
  4. Di wizard Create Proxy, klik Use OpenAPI Spec untuk template Reverse proxy (paling umum).
    Membuat jenis Proxy
  5. Klik Impor dari 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
    • Spec name: Nama untuk Spesifikasi OpenAPI, seperti Mock Target.

      Nama ini digunakan untuk menyimpan Spesifikasi OpenAPI di penyimpanan spesifikasi. Lihat Mengelola spesifikasi.

  6. Klik Import.

    Halaman Detail di wizard Buat Proxy akan ditampilkan. Kolom ini telah diisi sebelumnya menggunakan nilai yang ditetapkan dalam Spesifikasi OpenAPI, seperti ditunjukkan dalam

    Tabel berikut menjelaskan nilai default yang sudah diisi sebelumnya menggunakan properti dalam Spesifikasi OpenAPI. Kutipan Spesifikasi OpenAPI yang menggambarkan properti yang digunakan ditampilkan di bawah tabel.

    Kolom Deskripsi Default
    Name 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 organisasi Anda, lingkungan tempat proxy API ini di-deploy, dan jalur dasar ini. Sebagai contoh: http://myorg-test.apigee.net/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 adalah kutipan dari Spesifikasi OpenAPI yang menunjukkan properti yang digunakan untuk mengisi otomatis kolom ini.

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

    Lewati (tanpa otorisasi) yang dipilih pada halaman Kebijakan umum

  10. Pada halaman Flow, pastikan semua operasi dipilih. Membuat Alur Proxy
  11. Klik Next.
  12. Pada halaman Virtual hosts, pilih default dan secure, lalu klik Next.
    default dan aman yang dipilih pada halaman Host virtual
  13. Pada halaman Summary, pastikan lingkungan Test dipilih di bagian Optional Deployment lalu klik Create and deploy:

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

  14. Klik Edit proxy guna menampilkan halaman Ringkasan untuk proxy API.
    Ringkasan proxy Mock Target API

Edge Klasik (Private Cloud)

Untuk membuat proxy API dari Spesifikasi OpenAPI menggunakan UI Classic Edge:

  1. Login ke https://apigee.com/edge.
  2. Klik Proxy API di jendela utama.

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

  3. Klik + Proxy.
    Tambahkan proxy API
  4. Di wizard Create Proxy, pilih Reverse proxy (most common), lalu klik Use OpenAPI.
    Membuat jenis Proxy
  5. Klik Import from a URL, masukkan nama untuk OpenAPI Specification, dan masukkan jalur ke konten mentah di GitHub untuk OpenAPI Specification di kolom URL:

    https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget.yaml
  6. Klik Pilih.
  7. Klik Next.

    Halaman Detail di wizard Buat Proxy akan ditampilkan. Kolom ini telah diisi sebelumnya menggunakan nilai yang ditetapkan dalam Spesifikasi OpenAPI, seperti yang ditunjukkan dalam gambar berikut.

    Membuat Detail Proxy

    Tabel berikut menjelaskan nilai default yang sudah diisi sebelumnya menggunakan properti dalam Spesifikasi OpenAPI. Kutipan Spesifikasi OpenAPI yang menggambarkan properti yang digunakan ditampilkan di bawah tabel.

    Kolom Deskripsi Default
    Nama Proxy Nama proxy API. Misalnya: Mock-Target-API. Properti title dari Spesifikasi OpenAPI dengan spasi yang diganti dengan tanda hubung
    Jalur Dasar Proxy Komponen jalur yang mengidentifikasi proxy API ini secara unik dalam organisasi. URL yang dapat dilihat publik dari proxy API ini terdiri dari nama organisasi Anda, lingkungan tempat proxy API ini di-deploy, dan jalur dasar ini. Sebagai contoh: http://myorg-test.apigee.net/mock-target-api Konten kolom Name dikonversi ke semua huruf kecil
    API yang sudah 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
    Deskripsi Deskripsi proxy API. Properti description dari Spesifikasi OpenAPI

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

    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
...
  8. Edit kolom Description sebagai berikut: API proxy for the Apigee mock target service endpoint.
  9. Klik Next.
  10. Pada halaman Flow, pastikan semua operasi dipilih. Membuat Alur Proxy
  11. Klik Next.
  12. Di halaman Security, pilih Pass through (none) sebagai opsi keamanan, lalu klik Next.
  13. Di halaman Virtual Hosts, pastikan semua host virtual dipilih, lalu klik Next.
  14. Pada halaman Build, pastikan lingkungan test dipilih, lalu klik Build and Deploy.
  15. Di halaman Summary, Anda akan melihat konfirmasi bahwa proxy API baru berhasil dibuat dan di-deploy ke lingkungan pengujian.
    Membuat Ringkasan Proxy
  16. Klik Mock-Target-API guna menampilkan halaman Ringkasan untuk proxy API.
    Ringkasan proxy Mock Target 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.

Di jendela terminal, jalankan perintah cURL berikut. Ganti nama organisasi Anda di URL.

curl http://<org_name>-test.apigee.net/mock-target-api

Respons

Anda akan melihat respons berikut:

Hello, Guest!

Selamat! 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 bersyarat 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 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. Ganti nama organisasi Anda di URL.

curl http://<org_name>-test.apigee.net/mock-target-api/xml

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.

  1. Klik tab Develop di sudut kanan atas halaman Mock-Target-API Overview di Edge UI.
    Tab Developer
  2. Di panel Navigator kiri, di bagian Proxy Endpoints > default, klik alur kondisional View XML Response.
    Pilih View XML Response
  3. Klik tombol +Step bawah, yang sesuai dengan Response untuk alurnya.
    Pilih +Langkah
    Dialog Add Step akan terbuka dan menampilkan daftar kategori semua kebijakan yang dapat Anda tambahkan.
  4. Scroll ke kategori Mediasi, lalu pilih XML ke JSON.
    Dialog Tambahkan Langkah
  5. Pertahankan nilai default untuk Display Name dan Name.
  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 dalam proxy API akan mengonversi respons ke JSON. Lakukan panggilan ini:

curl http://<org_name>-test.apigee.net/mock-target-api/xml

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.