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

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

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

Tentang Open API Initiative

Inisiatif Open API
"Open API Initiative (OAI) difokuskan pada membuat, mengembangkan, dan mempromosikan Format Deskripsi API yang tidak terikat dengan vendor berdasarkan Swagger Spesifikasi". Untuk informasi selengkapnya tentang Open API Initiative, lihat https://openapis.org.

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

http://mocktarget.apigee.net

Layanan target akan menampilkan Hello, guest! ucapan

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

http://mocktarget.apigee.net/help

Yang Anda butuhkan

  • Akun Apigee Edge. Jika Anda belum memiliki akun, Anda dapat mendaftar dengan mengikuti petunjuk dalam Membuat Apigee Edge menggunakan akun layanan.
  • Spesifikasi OpenAPI. Dalam tutorial ini, Anda akan menggunakan mocktarget.yaml Spesifikasi OpenAPI yang menjelaskan target tiruan Apigee layanan, http://mocktarget.apigee.net. Untuk 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 baris perintah; atau {i>browser<i} web.

Membuat proxy API

Edge

Untuk membuat proxy API dari Spesifikasi OpenAPI menggunakan UI Edge:

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

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

    Klik Proxy API pada 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 Anda.

  6. Klik Impor.

    Halaman Detail di wizard Create Proxy akan ditampilkan. Kolom telah diisi otomatis dengan menggunakan nilai yang ditetapkan dalam Spesifikasi OpenAPI, seperti ditunjukkan

    Tabel berikut menjelaskan nilai default yang telah diisi otomatis menggunakan dalam Spesifikasi OpenAPI. Cuplikan Spesifikasi OpenAPI yang menggambarkan properti yang digunakan ditampilkan berikut tabel.

    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 proxy API ini yang ditampilkan ke publik terdiri dari nama organisasi Anda, tempat proxy API ini di-deploy, dan jalur dasar ini. Sebagai contoh: http://myorg-test.apigee.net/mock-target-api Konten kolom Name dikonversi menjadi huruf kecil semua
    Deskripsi Deskripsi proxy API. Properti description dari Spesifikasi OpenAPI
    Target (API yang Sudah Ada) URL target yang 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 adalah 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. Edit kolom Description sebagai berikut: API proxy for the Apigee mock target service endpoint.
  8. Klik Berikutnya.
  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. Di halaman Alur, pastikan semua operasi dipilih. Membangun Alur Proxy
  11. Klik Berikutnya.
  12. Di halaman Virtual hosts, pilih default dan secure, lalu klik Berikutnya.
    default dan aman dipilih pada halaman Host virtual
  13. Di halaman Summary, pastikan lingkungan Test sudah dipilih di bawah Deployment Opsional lalu klik Create and deploy:

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

  14. Klik Edit proxy untuk menampilkan halaman Ringkasan API {i>proxy<i}.
    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 > Proxy API di menu navigasi sebelah kiri.

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

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

    Halaman Detail di wizard Create Proxy akan ditampilkan. Kolom telah diisi otomatis dengan menggunakan nilai yang ditetapkan dalam Spesifikasi OpenAPI, seperti ditunjukkan gambar ini.

    Membuat Detail Proxy

    Tabel berikut menjelaskan nilai default yang telah diisi otomatis menggunakan dalam Spesifikasi OpenAPI. Cuplikan Spesifikasi OpenAPI yang menggambarkan properti yang digunakan ditampilkan berikut 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 proxy API ini yang ditampilkan ke publik terdiri dari nama organisasi Anda, tempat proxy API ini di-deploy, dan jalur dasar ini. Sebagai contoh: http://myorg-test.apigee.net/mock-target-api Konten kolom Name dikonversi menjadi huruf kecil semua
    API yang sudah ada URL target yang 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 ini merupakan 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
...
  8. Edit kolom Description sebagai berikut: API proxy for the Apigee mock target service endpoint.
  9. Klik Berikutnya.
  10. Di halaman Alur, pastikan semua operasi dipilih. Membangun Alur Proxy
  11. Klik Berikutnya.
  12. Di halaman Keamanan, pilih Lewati (tidak ada) sebagai keamanan lalu klik Next.
  13. Pada halaman {i>Virtual Hosts<i}, pastikan semua {i>host<i} virtual dipilih dan klik Berikutnya.
  14. Pada halaman Build, pastikan lingkungan test dipilih, dan klik Build and Deploy.
  15. Di halaman Summary, Anda akan melihat konfirmasi bahwa proxy API baru Anda telah dibuat berhasil dan di-deploy ke lingkungan pengujian Anda.
    Membuat Ringkasan Proxy
  16. Klik Mock-Target-API untuk menampilkan halaman Overview untuk API {i>proxy<i}.
    Ringkasan proxy Mock Target API

Selamat! Anda telah membuat proxy API dari Spesifikasi OpenAPI. Berikutnya, 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 menguji anotasi.

Menambahkan XML ke kebijakan JSON

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

Pertama, panggil API agar Anda dapat membandingkan hasil dengan hasil yang diterima setelah menambahkan kebijakan tersebut. 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 menjadi JSON. Menambahkan kebijakan XML ke JSON ke alur bersyarat View XML Response dalam proxy API.

  1. Klik tab Develop di sudut kanan atas Mock-Target-API Halaman Overview di UI Edge.
    Tab Developer
  2. Di panel Navigator sebelah kiri, di bagian Proxy Endpoints > klik tombol View Respons XML.
    Pilih Lihat Respons XML
  3. Klik tombol +Step bawah, yang sesuai dengan Respons untuk alur.
    Pilih +Langkah
    Dialog Tambahkan Langkah akan terbuka untuk menampilkan daftar yang dikategorikan dari semua kebijakan yang dapat tambahkan.
  4. Scroll ke kategori Mediasi dan pilih XML ke JSON.
    Dialog Add Step
  5. Simpan nilai default untuk Display Name 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 mengembalikan bloknya XML, tetapi sekarang kebijakan di proxy API akan mengonversi respons ke JSON. Buat ini hubungi:

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.