Memublikasikan API menggunakan Edge API

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

Bagian ini menjelaskan cara menggunakan Edge API untuk membuat produk API untuk dipublikasikan di portal developer.

Membuat produk API menggunakan API

Produk API memungkinkan developer mendaftarkan aplikasi yang menggunakan API menggunakan kunci API dan token akses OAuth. Produk API didesain agar Anda dapat 'memaketkan' resource API, lalu memublikasikan paket tersebut ke berbagai grup developer. Misalnya, Anda mungkin perlu memublikasikan satu kumpulan resource API ke developer partner, sementara Anda memublikasikan paket lain ke developer eksternal. Produk API memungkinkan Anda melakukan pemaketan ini dengan cepat, tanpa perlu mengubah API itu sendiri. Manfaat lainnya adalah akses developer dapat 'diupgrade' dan 'didowngrade' tanpa mengharuskan developer mendapatkan kunci konsumen baru untuk aplikasi mereka.

Untuk membuat produk API menggunakan API, berikan permintaan POST ke /organizations/{org_name}/apiproducts. Untuk informasi selengkapnya, lihat referensi API Membuat Produk API.

Permintaan berikut membuat produk API yang disebut weather_free. Produk API menyediakan akses ke semua API yang diekspos oleh proxy API yang disebut weatherapi, yang di-deploy di lingkungan test. Jenis persetujuan disetel ke auto yang menunjukkan bahwa permintaan akses apa pun akan disetujui.

curl -X POST https://api.enterprise.apigee.com/v1/organization/myorg/apiproducts \
-H "Content-Type:application/json" \
-d \
'{
  "approvalType": "auto",
  "displayName": "Free API Product",
  "name": "weather_free",
  "proxies": [ "weatherapi" ],
  "environments": [ "test" ]
}' \
-u email:password 

Contoh tanggapan:

{
  "apiResources" : [ ],
  "approvalType" : "auto",
  "attributes" : [ ],
  "createdAt" : 1362759663145,
  "createdBy" : "developer@apigee.com",
  "displayName" : "Free API Product",
  "environments" : [ "test" ],
  "lastModifiedAt" : 1362759663145,
  "lastModifiedBy" : "developer@apigee.com",
  "name" : "weather_free",
  "proxies" : [ "weatherapi" ],
  "scopes" : [ ]
}

Produk API yang dibuat di atas menerapkan skenario paling dasar, yang mengizinkan permintaan ke proxy API di lingkungan. Kebijakan ini menentukan produk API yang memungkinkan aplikasi yang diotorisasi dapat mengakses setiap resource API yang diakses melalui proxy API yang berjalan di lingkungan pengujian. Produk API mengekspos setelan konfigurasi tambahan yang memungkinkan Anda menyesuaikan kontrol akses ke API untuk berbagai grup developer. Misalnya, Anda dapat membuat dua produk API yang menyediakan akses ke proxy API yang berbeda. Anda juga dapat membuat dua produk API yang menyediakan akses ke proxy API yang sama, tetapi dengan setelan Kuota terkait yang berbeda.

Setelan konfigurasi produk API

Produk API menampilkan opsi konfigurasi berikut:

Nama Deskripsi Default Wajib diisi?
apiResources

Daftar URI yang dipisahkan koma, atau jalur resource, yang 'dipaketkan' ke dalam produk API.

Secara default, jalur resource dipetakan dari variabel proxy.pathsuffix. Akhiran jalur proxy ditentukan sebagai fragmen URI yang mengikuti jalur dasar ProxyEndpoint. Misalnya, dalam contoh produk API di bawah, elemen apiResources ditentukan sebagai /forecastrss. Karena Jalur Dasar yang ditentukan untuk proxy API ini adalah /weather, artinya hanya permintaan ke /weather/forecastrss yang diizinkan oleh produk API ini.

Anda dapat memilih jalur tertentu, atau memilih semua subjalur dengan karakter pengganti. Karakter pengganti (/** dan /*) didukung. Karakter pengganti tanda bintang ganda menunjukkan bahwa semua sub-URI disertakan. Tanda bintang tunggal menunjukkan bahwa hanya URI satu tingkat ke bawah yang disertakan.

Secara default, '/' mendukung resource yang sama seperti '/**' serta Jalur Dasar yang ditentukan oleh proxy API. Misalnya, jika Jalur Dasar proxy API adalah /v1/weatherapikey, maka produk API mendukung permintaan ke /v1/weatherapikey dan ke sub-URI apa pun, seperti /v1/weatherapikey/forecastrss, /v1/weatherapikey/region/CA, dan seterusnya. Lihat Mengelola produk API untuk informasi tentang cara mengubah perilaku default ini.

T/A Tidak
approvalType Menentukan cara kunci API disetujui untuk mengakses API yang ditentukan oleh produk API. Jika ditetapkan ke manual, kunci yang dihasilkan untuk aplikasi akan berada dalam status 'tertunda'. Kunci tersebut tidak akan berfungsi sebelum disetujui secara eksplisit. Jika ditetapkan ke auto, semua kunci akan dibuat di file 'disetujui' dan langsung berfungsi. (auto biasanya digunakan untuk menyediakan akses ke produk API uji coba gratis yang memberikan Kuota atau kemampuan terbatas.) T/A Ya
attributes

Array atribut yang dapat digunakan untuk memperluas profil produk API default dengan metadata khusus pelanggan.

Gunakan properti ini untuk menentukan tingkat akses produk API sebagai publik, pribadi, atau internal. Contoh:
"attributes": [
"name": "akses",
"value": "public"
},
"name": "foo",
"value": "foo"
},
{
"name": "bar",
"value": "bar"
}
]
T/A Tidak
scopes Daftar cakupan OAuth yang dipisahkan koma yang divalidasi saat runtime. (Apigee Edge memvalidasi bahwa cakupan dalam setiap token akses yang disajikan cocok dengan cakupan yang ditetapkan dalam produk API.) T/A Tidak
proxies Proxy API bernama yang terikat dengan produk API ini. Dengan menentukan proxy, Anda dapat mengaitkan resource di produk API dengan proxy API tertentu, sehingga mencegah developer mengakses resource tersebut melalui proxy API lainnya. T/A Tidak. Jika tidak ditentukan, apiResources harus ditentukan secara eksplisit (lihat info untuk apiResources di atas), dan variabel flow.resource.name ditetapkan dalam kebijakan ProvideMessage.
environments Lingkungan bernama (misalnya 'test' atau 'prod") yang terikat dengan produk API ini. Dengan menentukan satu atau beberapa lingkungan, Anda dapat mengikat resource yang tercantum dalam produk API ke lingkungan tertentu, sehingga mencegah developer mengakses resource tersebut melalui proxy API di lingkungan lain. Setelan ini digunakan, misalnya, untuk mencegah resource yang terkait dengan proxy API di 'prod' diakses oleh proxy API yang di-deploy di 'test'. T/A Tidak. Jika tidak ditentukan, apiResources harus ditentukan secara eksplisit, dan variabel flow.resource.name ditetapkan dalam kebijakan ProvideMessage.
quota Jumlah permintaan yang diizinkan per aplikasi selama interval waktu yang ditentukan. T/A Tidak
quotaInterval Jumlah unit waktu yang digunakan untuk mengevaluasi kuota T/A Tidak
quotaTimeUnit Unit waktu (menit, jam, hari, atau bulan) yang digunakan untuk menghitung kuota. T/A Tidak

Berikut ini contoh yang lebih detail untuk membuat produk API.

curl -X POST  https://api.enterprise.apigee.com/v1/o/{org_name}/apiproducts \
-H "Content-Type:application/json" -d \
'{
  "apiResources": [ "/forecastrss" ],
  "approvalType": "auto", 
  "attributes":
    [ {"name": "access", "value": "public"} ],
  "description": "Free API Product",
  "displayName": "Free API Product",
  "name": "weather_free",
  "scopes": [],
  "proxies": [ "weatherapi" ],
  "environments": [ "test" ],
  "quota": "10",
  "quotaInterval": "2",
  "quotaTimeUnit": "hour" }' \
-u email:password

Contoh Respons

{
  "apiResources" : [ "/forecastrss" ],
  "approvalType" : "auto",
  "attributes" : [ {
    "name" : "access",
    "value" : "public"
  },
  "createdAt" : 1344454200828,
  "createdBy" : "admin@apigee.com",
  "description" : "Free API Product",
  "displayName" : "Free API Product",
  "lastModifiedAt" : 1344454200828,
  "lastModifiedBy" : "admin@apigee.com",
  "name" : "weather_free",
  "scopes" : [ ],
  "proxies": [ {'weatherapi'} ],
  "environments": [ {'test'} ],
  "quota": "10",
  "quotaInterval": "1",
  "quotaTimeUnit": "hour"}'
}

Tentang cakupan

Cakupan adalah konsep yang diambil dari OAuth dan memetakan secara kasar konsep 'izin'. Di Apigee Edge, cakupan sepenuhnya bersifat opsional. Anda dapat menggunakan cakupan untuk mencapai otorisasi yang lebih terperinci. Setiap kunci konsumen yang dikeluarkan untuk aplikasi dikaitkan dengan 'cakupan master'. Cakupan master adalah kumpulan semua cakupan di semua produk API untuk aplikasi ini yang telah disetujui. Untuk aplikasi yang disetujui untuk menggunakan beberapa produk API, cakupan master adalah gabungan dari semua cakupan yang ditentukan dalam produk API yang kunci konsumennya telah disetujui.

Lihat produk API

Untuk melihat produk API yang dibuat untuk organisasi menggunakan API, lihat bagian berikut:

Berikut ini contoh cara melihat produk API menggunakan API:

curl -X GET "https://ext.apiexchange.org/v1/mint/organizations/{org_name}/products?monetized=true" \
  -H "Accept:application/json" \
  -u email:password

Respons seharusnya terlihat seperti ini (hanya sebagian respons yang ditampilkan):

{
  "product" : [ {
    "customAtt1Name" : "user",
    "customAtt2Name" : "response size",
    "customAtt3Name" : "content-length",
    "description" : "payment api product",
    "displayName" : "payment",
    "id" : "payment",
    "name" : "payment",
    "organization" : {
      ...
    },
    "pricePoints" : [ ],
    "status" : "CREATED",
    "transactionSuccessCriteria" : "status == 'SUCCESS'"
  }, {
    "customAtt1Name" : "user",
    "customAtt2Name" : "response size",
    "customAtt3Name" : "content-length",
    "description" : "messaging api product",
    "displayName" : "messaging",
    "id" : "messaging",
    "name" : "messaging",
    "organization" : ...
    },
    "pricePoints" : [ ],
    "status" : "CREATED",
    "transactionSuccessCriteria" : "status == 'SUCCESS'"
  } ],
  "totalRecords" : 2
}

Mendaftarkan developer menggunakan API

Semua aplikasi dimiliki oleh developer atau perusahaan. Oleh karena itu, untuk membuat aplikasi, Anda harus terlebih dahulu mendaftarkan developer atau perusahaan.

Developer terdaftar di organisasi dengan membuat profil. Perlu diperhatikan bahwa email developer yang disertakan dalam profil digunakan sebagai kunci unik untuk developer di seluruh Apigee Edge.

Untuk mendukung monetisasi, Anda harus menentukan atribut monetisasi saat membuat atau mengedit developer. Anda juga dapat menentukan atribut arbitrer lainnya untuk digunakan dalam analisis kustom, penerapan kebijakan kustom, dan sebagainya; atribut arbitrer ini tidak akan ditafsirkan oleh Apigee Edge,

Misalnya, permintaan berikut mendaftarkan profil untuk developer yang alamat emailnya adalah ntesla@theremin.com dan menentukan subkumpulan atribut monetisasi menggunakan Create developer API:

$ curl -H "Content-type:application/json" -X POST -d \
'{"email" : "ntesla@theremin.com", 
  "firstName" : "Nikola", 
  "lastName" : "Tesla", 
  "userName" : "theremin", 
  "attributes" : [ 
  { 
    "name" : "project_type", 
    "value" : "public"
  },
  {    
   "name": "MINT_BILLING_TYPE",
   "value": "POSTPAID"
  },
  {
   "name": "MINT_DEVELOPER_ADDRESS",
   "value": "{\"address1\":\"Dev One Address\",\"city\":\"Pleasanton\",\"country\":\"US\",\"isPrimary\":true,\"state\":\"CA\",\"zip\":\"94588\"}"
  },
  {
   "name": "MINT_DEVELOPER_TYPE",
   "value": "TRUSTED"
  },
  {    
   "name": "MINT_HAS_SELF_BILLING,
   "value": "FALSE"
  },
  {
   "name" : "MINT_SUPPORTED_CURRENCY",
   "value" : "usd"
  }
 ] 
}' \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers \
-u email:password 

Contoh Respons

{
          "email" : "ntesla@theremin.com",
          "firstName" : "Nikola",
          "lastName" : "Tesla",
          "userName" : "theremin",
          "organizationName" : "{org_name}",
          "status" : "active",
          "attributes" : [ 
          {
            "name" : "project_type",
            "value" : "public"
          },
          {    
             "name": "MINT_BILLING_TYPE",
             "value": "POSTPAID"
          },
          {
             "name": "MINT_DEVELOPER_ADDRESS",
             "value": "{\"address1\":\"Dev One Address\",\"city\":\"Pleasanton\",\"country\":\"US\",\"isPrimary\":true,\"state\":\"CA\",\"zip\":\"94588\"}"
          },
          {
             "name": "MINT_DEVELOPER_TYPE",
             "value": "TRUSTED"
          },
          {    
             "name": "MINT_HAS_SELF_BILLING,
             "value": "FALSE"
          },
          {
             "name" : "MINT_SUPPORTED_CURRENCY",
             "value" : "usd"
          } 
          ],
          "createdAt" : 1343189787717,
          "createdBy" : "admin@apigee.com",
          "lastModifiedAt" : 1343189787717,
          "lastModifiedBy" : "admin@apigee.com"
        }

Mendaftarkan aplikasi developer menggunakan API

Setiap aplikasi yang terdaftar di Apigee Edge dikaitkan dengan developer dan produk API. Saat aplikasi didaftarkan atas nama developer, Apigee Edge akan menghasilkan "kredensial" (pasangan kunci dan rahasia konsumen) yang mengidentifikasi aplikasi. Selanjutnya, aplikasi harus meneruskan kredensial ini sebagai bagian dari setiap permintaan ke produk API yang terkait dengan aplikasi.

Permintaan berikut menggunakan Create Developer App API untuk mendaftarkan aplikasi bagi developer yang Anda buat di atas: ntesla@theremin.com. Saat mendaftarkan aplikasi, Anda menentukan nama untuk aplikasi, callbackUrl, dan daftar satu atau beberapa produk API:
$ curl -H "Content-type:application/json" -X POST -d \
'{
  "apiProducts": [ "weather_free"], 
  "callbackUrl" : "login.weatherapp.com", 
  "keyExpiresIn" : "2630000000",
  "name" : "weatherapp"}' \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps \
-u email:password 

callbackUrl digunakan oleh beberapa jenis pemberian izin OAuth (seperti kode otorisasi) untuk memvalidasi permintaan pengalihan dari aplikasi. Jika Anda menggunakan OAuth, nilai ini harus ditetapkan ke nilai yang sama dengan redirect_uri yang digunakan untuk membuat permintaan OAuth.

Atribut keyExpiresIn menentukan, dalam milidetik, selama masa pakai kunci konsumen yang akan dihasilkan untuk aplikasi developer. Nilai default, -1, menunjukkan periode validitas yang tak terbatas.

Contoh Respons

{
  "appId": "5760d130-528f-4388-8c6f-65a6b3042bd1",
  "attributes": [
    {
      "name": "DisplayName",
      "value": "Test Key Expires"
    },
    {
      "name": "Notes",
      "value": "Just testing this attribute"
    }
  ],
  "createdAt": 1421770824390,
  "createdBy": "wwitman@apigee.com",
  "credentials": [
    {
      "apiProducts": [
        {
          "apiproduct": "ProductNoResources",
          "status": "approved"
        }
      ],
      "attributes": [],
      "consumerKey": "jcAFDcfwImkJ19A5gTsZRzfBItlqohBt",
      "consumerSecret": "AX7lGGIRJs6s8J8y",
      "expiresAt": 1424400824401,
      "issuedAt": 1421770824401,
      "scopes": [],
      "status": "approved"
    }
  ],
  "developerId": "e4Oy8ddTo3p1BFhs",
  "lastModifiedAt": 1421770824390,
  "lastModifiedBy": "wwitman@apigee.com",
  "name": "TestKeyExpires",
  "scopes": [],
  "status": "approved"
}

Mengelola kunci konsumen untuk aplikasi yang menggunakan API

Mendapatkan kunci konsumen (Kunci API) untuk aplikasi

Kredensial untuk sebuah aplikasi (produk API, kunci konsumen, dan rahasia) ditampilkan sebagai bagian dari profil aplikasi. Administrator organisasi dapat mengambil kunci konsumen kapan saja.

Profil aplikasi menampilkan nilai kunci dan rahasia konsumen, status kunci konsumen, serta pengaitan produk API apa pun untuk kunci tersebut. Sebagai admin, Anda dapat mengambil profil kunci konsumen kapan saja menggunakan Get Key Details untuk Developer App API:

$ curl -X GET -H "Accept: application/json" \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J \
-u email:password

Contoh Respons

{
  "apiProducts" : [ {
    "apiproduct" : "weather_free",
    "status" : "approved"
  } ],
  "attributes" : [ ],
  "consumerKey" : "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
  "consumerSecret" : "1eluIIdWG3JGDjE0",
  "status" : "approved"
}

Lihat Mendapatkan Detail Kunci untuk Aplikasi Developer untuk mengetahui informasi selengkapnya.

Menambahkan produk API ke aplikasi dan kunci

Untuk mengupdate aplikasi agar dapat menambahkan produk API baru, Anda sebenarnya dapat menambahkan produk API ke kunci aplikasi menggunakan Add API Product to Key API. Lihat Menambahkan Produk API ke Kunci untuk informasi selengkapnya.

Menambahkan produk API ke kunci aplikasi memungkinkan aplikasi yang menyimpan kunci tersebut untuk mengakses resource API yang dipaketkan dalam produk API. Panggilan metode berikut menambahkan produk API baru ke aplikasi:

$ curl -H "Content-type:application/json" -X POST -d \
'{
  "apiProducts": [ "newAPIProduct"]
}' \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J \
-u email:password 

Contoh Respons:

{
  "apiProducts": [
   {
     "apiproduct": "weather_free",
     "status": "approved"
   },
   {
     "apiproduct": "newAPIProduct",
     "status": "approved"
   }
 ],
 "attributes": [],
 "consumerKey": "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
 "consumerSecret": "1eluIIdWG3JGDjE0",
 "expiresAt": -1,
 "issuedAt": 1411491156464,
 "scopes": [],
 "status": "approved"
 }

Menyetujui kunci konsumen

Menetapkan jenis persetujuan ke manual memungkinkan Anda mengontrol developer mana yang dapat mengakses resource yang dilindungi oleh produk API. Jika produk API menetapkan persetujuan kunci ke manual, kunci konsumen harus disetujui secara eksplisit. Kunci dapat disetujui secara eksplisit menggunakan Setujui atau Cabut Kunci Tertentu dari Aplikasi Developer API:

$ curl -X POST -H "Content-type:appilcation/octet-stream" \ 
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J?"action=approve" \
-u email:password

Contoh Respons

{
  "apiProducts" : [ {
  "apiproduct" : "weather_free",
  "status" : "approved"
} ],
  "attributes" : [ ],
  "consumerKey" : "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
  "consumerSecret" : "1eluIIdWG3JGDjE0",
  "status" : "approved"
}

Lihat Menyetujui atau Mencabut Kunci Tertentu Aplikasi Developer untuk mengetahui informasi selengkapnya.

Menyetujui produk API untuk kunci konsumen

Pengaitan produk API dengan kunci konsumen juga memiliki status. Agar akses API berhasil, kunci konsumen harus disetujui, dan kunci konsumen harus disetujui untuk produk API yang sesuai. Pengaitan kunci konsumen dengan produk API dapat disetujui dengan menggunakan Setujui atau Cabut Produk API untuk Kunci untuk Aplikasi Developer API:

$ curl -X POST -H "Content-type:application/octet-stream" \ 
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J/apiproducts/weather_free?"action=approve" \
-u email:password

Perintah cURL ini tidak menampilkan respons. Lihat Menyetujui atau Mencabut Produk API untuk Kunci Aplikasi Developer untuk mengetahui informasi selengkapnya.

Mencabut produk API untuk kunci konsumen

Ada banyak alasan mengapa Anda perlu mencabut pengaitan kunci konsumen dengan produk API. Anda mungkin harus menghapus produk API dari kunci konsumen karena developer belum membayar, periode uji coba sudah berakhir, atau Saat aplikasi dipromosikan dari satu produk API ke produk API lainnya.

Untuk mencabut pengaitan kunci konsumen dengan produk API, gunakan Setujui atau Cabut Kunci Khusus Developer App API, menggunakan tindakan pencabutan terhadap kunci konsumen dari aplikasi pengembangan:

$ curl -X POST -H "Content-type:application/octet-stream" \ 
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J/apiproducts/weather_free?"action=revoke" \
-u email:password

Perintah cURL ini tidak menampilkan respons. Lihat Menyetujui atau Mencabut Kunci Tertentu Aplikasi Developer untuk mengetahui informasi selengkapnya.

Menerapkan setelan produk API

Agar produk API diterapkan, salah satu jenis kebijakan berikut harus disertakan ke alur proxy API:

  • VerifyAPIKey: Mengambil referensi ke kunci API, memverifikasi bahwa referensi tersebut mewakili aplikasi yang valid, dan cocok dengan produk API. Lihat Kebijakan Verifikasi Kunci API untuk informasi selengkapnya.
  • OAuthV1, operasi “VerifyAccessToken”: Memverifikasi tanda tangan, memvalidasi token akses dan “kunci konsumen” OAuth 1.0a”, serta mencocokkan aplikasi dengan produk API. Lihat kebijakan OAuth v1.0a untuk informasi selengkapnya.
  • OAuthV2, operasi “VerifyAccessToken”: Memverifikasi bahwa token akses OAuth 2.0 valid, mencocokkan token dengan aplikasi, memverifikasi bahwa aplikasi valid, lalu mencocokkan aplikasi dengan produk API. Lihat rumah OAuth untuk mengetahui informasi selengkapnya.

Setelah kebijakan dan produk API dikonfigurasi, proses berikut dijalankan oleh Apigee Edge:

  1. Permintaan diterima oleh Apigee Edge dan diarahkan ke proxy API yang sesuai.
  2. Kebijakan dijalankan yang memverifikasi kunci API atau token akses OAuth yang ditampilkan oleh klien.
  3. Edge menyelesaikan Kunci API atau token akses ke profil aplikasi.
  4. Edge menyelesaikan daftar (jika ada) produk API yang terkait dengan aplikasi.
  5. Produk API pertama yang cocok digunakan untuk mengisi variabel Kuota.
  6. Jika tidak ada produk API yang cocok dengan kunci API atau token akses, permintaan akan ditolak.
  7. Edge menerapkan kontrol akses berbasis URI (lingkungan, proxy API, dan jalur URI) berdasarkan setelan produk API, beserta setelan Kuota.