Membuat proxy API dari Spesifikasi OpenAPI

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

Yang akan Anda pelajari

Dalam tutorial ini, Anda akan mempelajari cara:

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

Dalam tutorial ini, Anda akan mempelajari cara membuat proxy API Edge 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 Open API Initiative

Inisiatif OpenAPI
"The 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 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 ini mendeskripsikan elemen API seperti jalur dasar, jalur dan kata kerja, header, parameter kueri, operasi, jenis konten, deskripsi respons, dan lainnya. Selain itu, Spesifikasi OpenAPI umum 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. Layanan ini tidak memerlukan kunci API atau token akses. Bahkan, Anda dapat mengaksesnya di browser web. Coba dengan mengklik hal berikut:

http://mocktarget.apigee.net

Layanan target menampilkan ucapan Hello, guest!

Untuk mengetahui informasi tentang kumpulan lengkap API yang didukung layanan target tiruan, klik hal berikut:

http://mocktarget.apigee.net/help

Yang akan Anda butuhkan

  • Akun Apigee Edge. Jika tidak memiliki akun, Anda dapat mendaftar dengan mengikuti petunjuk di Membuat akun Apigee Edge akun.
  • 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 https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.
  • cURL 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 UI Edge:

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

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

    Klik API Proxies di halaman landing

  3. Klik + Proxy.
    Menambahkan proxy API
  4. Di wizard Create Proxy, klik Use OpenAPI Spec untuk template Reverse proxy (most common).
    Membangun jenis Proxy
  5. Klik Import from 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
    • 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 Import.

    Halaman Details di wizard Create Proxy akan ditampilkan. Kolom diisi otomatis menggunakan nilai yang ditentukan dalam Spesifikasi OpenAPI, seperti yang ditunjukkan pada gambar berikut

    Tabel berikut menjelaskan nilai default yang diisi otomatis menggunakan properti dalam Spesifikasi OpenAPI. Kutipan Spesifikasi OpenAPI yang mengilustrasikan properti yang digunakan ditampilkan setelah tabel.

    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 publik proxy API ini terdiri dari nama organisasi Anda, an lingkungan tempat proxy API ini di-deploy, dan jalur dasar ini. Misalnya: 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 Ada) URL target yang dipanggil atas nama proxy API ini. URL apa pun yang dapat diakses melalui Internet terbuka dapat digunakan. Misalnya: 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 Next.
  9. Di halaman Common policies , di 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 Next.
  12. Di halaman Virtual hosts, pilih default dan secure, lalu klik Next.
    default dan secure dipilih di halaman Virtual hosts
  13. Di 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 Anda:

  14. Klik Edit proxy untuk menampilkan halaman Overview untuk proxy API proxy.
    Ringkasan proxy API Target Tiruan

Classic Edge (Private Cloud)

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

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

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

  3. Klik + Proxy.
    Menambahkan proxy API
  4. Di wizard Create Proxy, pilih Reverse proxy (most common) , lalu klik Use OpenAPI.
    Membangun jenis Proxy
  5. Klik Import from a URL, masukkan nama untuk Spesifikasi OpenAPI, lalu masukkan 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/mocktarget.yaml
  6. Klik Select.
  7. Klik Next.

    Halaman Details di wizard Create Proxy akan ditampilkan. Kolom diisi otomatis menggunakan nilai yang ditentukan dalam Spesifikasi OpenAPI, seperti yang ditunjukkan pada gambar berikut.

    Membangun Detail Proxy

    Tabel berikut menjelaskan nilai default yang diisi otomatis menggunakan properti dalam Spesifikasi OpenAPI. Kutipan Spesifikasi OpenAPI yang mengilustrasikan properti yang digunakan ditampilkan setelah tabel.

    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 Proxy Komponen jalur yang secara unik mengidentifikasi proxy API ini dalam organisasi. URL publik proxy API ini terdiri dari nama organisasi Anda, an lingkungan tempat proxy API ini di-deploy, dan jalur dasar ini. Misalnya: http://myorg-test.apigee.net/mock-target-api Konten kolom Name dikonversi menjadi huruf kecil semua
    API yang Ada URL target yang dipanggil atas nama proxy API ini. URL apa pun yang dapat diakses melalui Internet terbuka dapat digunakan. Misalnya: http://mocktarget.apigee.net Properti servers dari Spesifikasi OpenAPI
    Deskripsi Deskripsi proxy API. Properti description 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
...
  8. Edit kolom Description sebagai berikut: API proxy for the Apigee mock target service endpoint.
  9. Klik Next.
  10. Di halaman Flows, pastikan semua operasi dipilih. Membangun 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. Di halaman Build, pastikan lingkungan test dipilih, lalu klik Build and Deploy.
  15. Di halaman Summary, Anda akan melihat konfirmasi bahwa proxy API baru Anda berhasil dibuat berhasil dibuat dan di-deploy ke lingkungan pengujian Anda.
    Membangun Ringkasan Proxy
  16. Klik Mock-Target-API untuk menampilkan halaman Overview untuk proxy API proxy.
    Ringkasan proxy API Target Tiruan

Selamat! Anda telah membuat proxy API dari Spesifikasi OpenAPI. Selanjutnya, Anda akan mengujinya untuk melihat cara kerjanya.

Menguji proxy API

Anda dapat menguji API Mock-Target-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 membuat proxy API sederhana dari Spesifikasi OpenAPI dan mengujinya.

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

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

  1. Klik tab Develop di sudut kanan atas halaman Overview Mock-Target-API di UI Edge.
    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 +Step di bagian bawah, yang sesuai dengan Response untuk alur.
    Pilih +Langkah
    Dialog Add Step akan terbuka untuk menampilkan daftar kebijakan yang dikategorikan yang dapat Anda tambahkan.
  4. Scroll ke kategori Mediation dan pilih XML to JSON.
    Dialog Tambahkan Langkah
  5. Pertahankan nilai default untuk Display Name dan Name.
  6. Klik Add. Kebijakan XML ke JSON diterapkan ke respons.Kebijakan XML ke JSON dalam alur
  7. Klik Save.

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 sekarang kebijakan di proxy API akan mengonversi respons menjadi JSON. Lakukan panggilan ini:

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

Perhatikan bahwa respons XML dikonversi menjadi JSON:

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

Selamat! Anda telah berhasil menguji eksekusi kebijakan yang ditambahkan ke alur bersyarat.