Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi
Apigee X. info
Bagian ini menjelaskan cara menggunakan Edge API untuk membuat produk API yang akan 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 dirancang untuk memungkinkan Anda 'menggabungkan' resource API, lalu memublikasikan gabungan tersebut ke berbagai grup developer. Misalnya, Anda mungkin perlu memublikasikan satu set resource API ke developer partner, sementara Anda memublikasikan paket lain ke developer eksternal. Produk API memungkinkan Anda melakukan penggabungan ini secara langsung, tanpa memerlukan perubahan pada API itu sendiri. Manfaat tambahan adalah akses developer dapat 'diupgrade' dan 'diturunkan' tanpa mengharuskan developer mendapatkan kunci konsumen baru untuk aplikasi mereka.
Untuk membuat produk API menggunakan API, kirim permintaan POST ke
/organizations/{org_name}/apiproducts.
Untuk mengetahui informasi selengkapnya, lihat referensi API Create API Product.
Permintaan berikut membuat produk API yang disebut weather_free. Produk API
memberikan akses ke semua API yang diekspos oleh proxy API yang disebut weatherapi yang di-deploy di lingkungan test. Jenis persetujuan ditetapkan ke auto yang menunjukkan bahwa setiap permintaan akses 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 respons:
{ "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 mengimplementasikan skenario paling dasar, yaitu mengizinkan permintaan ke proxy API di lingkungan. Objek ini menentukan produk API yang memungkinkan aplikasi yang diberi otorisasi mengakses resource API apa pun 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 memberikan 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 mengekspos opsi konfigurasi berikut:
| Nama | Deskripsi | Default | Wajib? |
|---|---|---|---|
apiResources |
Daftar URI yang dipisahkan koma, atau jalur resource, yang 'digabungkan' ke dalam produk API. Secara default, jalur resource dipetakan dari variabel Anda dapat memilih jalur tertentu, atau Anda dapat memilih semua subjalur dengan karakter pengganti.
Karakter pengganti (/** dan /*) didukung. Karakter pengganti bintang ganda menunjukkan bahwa semua
sub-URI disertakan. Satu tanda bintang menunjukkan bahwa hanya URI satu tingkat di bawah yang disertakan. |
T/A | Tidak |
approvalType |
Menentukan cara kunci API disetujui untuk mengakses API yang ditentukan oleh produk API. Jika
ditetapkan ke manual, kunci yang dibuat untuk aplikasi berada dalam status 'tertunda'.
Kunci tersebut tidak akan berfungsi hingga disetujui secara eksplisit. Jika disetel ke auto,
semua kunci dibuat dalam status 'disetujui' dan langsung berfungsi. (auto biasanya digunakan untuk memberikan akses ke produk API gratis/uji coba yang menyediakan 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 public, private, atau internal. Contoh:
"attributes": [
{
"name": "access",
"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 token akses yang diberikan 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 dalam produk API dengan proxy API tertentu, sehingga mencegah developer mengakses resource tersebut melalui proxy API lain. | 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 AssignMessage. |
environments |
Lingkungan bernama (misalnya 'test' atau 'prod") yang menjadi tempat produk API ini terikat. 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 AssignMessage. |
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 adalah contoh yang lebih mendetail 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 secara kasar dipetakan ke konsep 'izin'. Di Apigee Edge, cakupan sepenuhnya bersifat opsional. Anda dapat menggunakan cakupan untuk mendapatkan otorisasi yang lebih mendetail. Setiap kunci konsumen yang dikeluarkan untuk aplikasi dikaitkan dengan 'cakupan utama'. Cakupan master adalah kumpulan semua cakupan di semua produk API yang telah disetujui untuk aplikasi ini. Untuk aplikasi yang disetujui untuk menggunakan beberapa produk API, cakupan utama adalah gabungan dari semua cakupan yang ditentukan dalam produk API yang telah disetujui kunci konsumennya.
Melihat produk API
Untuk melihat produk API yang dibuat untuk organisasi menggunakan API, lihat bagian berikut:
- Melihat produk API (dimonetisasi)
Secara default, hanya produk API yang dimonetisasi yang ditampilkan (yaitu, produk API dengan minimal satu paket tarif yang dipublikasikan). Untuk menampilkan semua produk API, tetapkan parameter kueri
monetizedkefalse. Hal ini setara dengan mengirimkan permintaan GET ke API produk List API yang tidak dimonetisasi:https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts?expand=true - Melihat produk API (tidak dimonetisasi)
- Melihat produk API yang memenuhi syarat untuk developer
- Melihat produk API yang memenuhi syarat untuk perusahaan
Berikut adalah 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
Responsnya akan 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 mendaftarkan developer atau perusahaan terlebih dahulu.
Developer terdaftar di organisasi dengan membuat profil. Perhatikan 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 subset atribut monetisasi
menggunakan API Buat developer:
$ 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. Setelah aplikasi didaftarkan atas nama developer, Apigee Edge akan membuat "kredensial" (pasangan kunci dan rahasia konsumen) yang mengidentifikasi aplikasi. Kemudian, aplikasi harus meneruskan kredensial ini sebagai bagian dari setiap permintaan ke produk API yang terkait dengan aplikasi.
Permintaan berikut menggunakan API Create Developer App 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 disetel ke nilai yang sama dengan redirect_uri
yang digunakan untuk membuat permintaan OAuth.
Atribut keyExpiresIn menentukan, dalam milidetik, masa berlaku
kunci konsumen yang akan dibuat untuk aplikasi developer. Nilai default, -1, menunjukkan
masa berlaku yang tidak 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 menggunakan API
Dapatkan kunci konsumen (Kunci API) untuk aplikasi
Kredensial untuk aplikasi (produk API, kunci pengguna 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 semua asosiasi produk API untuk kunci tersebut. Sebagai admin, Anda dapat mengambil profil kunci konsumen kapan saja menggunakan Get Key Details for a 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 guna menambahkan produk API baru, Anda sebenarnya menambahkan produk API ke kunci aplikasi menggunakan Add API Product to Key API. Lihat Menambahkan Produk API ke Kunci untuk mengetahui informasi selengkapnya.
Menambahkan produk API ke kunci aplikasi memungkinkan aplikasi yang memiliki kunci tersebut mengakses resource API yang disertakan 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
Dengan menyetel jenis persetujuan ke manual, Anda dapat mengontrol developer mana yang dapat mengakses resource yang dilindungi oleh produk API. Jika produk API memiliki persetujuan kunci yang ditetapkan ke manual, kunci konsumen harus disetujui secara eksplisit. Kunci dapat
disetujui secara eksplisit menggunakan API Menyetujui atau Mencabut Kunci Spesifik Aplikasi Developer:
$ 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 pengguna juga memiliki status. Agar akses API berhasil, kunci pengguna harus disetujui, dan kunci pengguna harus disetujui untuk produk API yang sesuai. Pengaitan kunci konsumen dengan produk API dapat disetujui menggunakan API Menyetujui atau Mencabut Produk API untuk Kunci bagi Aplikasi Developer:
$ 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 mungkin perlu mencabut hubungan kunci konsumen dengan produk API. Anda mungkin perlu menghapus produk API dari kunci pengguna karena tidak ada pembayaran dari developer, periode uji coba telah berakhir, atau saat aplikasi dipromosikan dari satu produk API ke produk API lainnya.
Untuk mencabut pengaitan kunci konsumen dengan produk API, gunakan API Menyetujui atau Mencabut Kunci Spesifik Aplikasi Developer , menggunakan tindakan pencabutan terhadap kunci konsumen aplikasi developer:
$ 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 dilampirkan ke alur proxy API:
- VerifyAPIKey: Mengambil referensi ke kunci API, memverifikasi bahwa kunci tersebut mewakili aplikasi yang valid, dan cocok dengan produk API. Lihat Kebijakan Verifikasi Kunci API untuk mengetahui informasi selengkapnya.
- OAuthV1, operasi “VerifyAccessToken”: Memverifikasi tanda tangan, memvalidasi token akses OAuth 1.0a dan “kunci pengguna”, serta mencocokkan aplikasi dengan produk API. Dukungan untuk OAuth 1.0a tidak digunakan lagi; lihat Fitur yang tidak digunakan lagi.
- 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 halaman beranda OAuth untuk mengetahui informasi selengkapnya.
Setelah kebijakan dan produk API dikonfigurasi, proses berikut akan dijalankan oleh Apigee Edge:
- Permintaan diterima oleh Apigee Edge dan dirutekan ke proxy API yang sesuai.
- Kebijakan dijalankan yang memverifikasi kunci API atau token akses OAuth yang diberikan oleh klien.
- Edge menyelesaikan Kunci API atau token akses ke profil aplikasi.
- Edge menyelesaikan daftar (jika ada) produk API yang terkait dengan aplikasi.
- Produk API pertama yang cocok digunakan untuk mengisi variabel Kuota.
- Jika tidak ada produk API yang cocok dengan kunci API atau token akses, permintaan akan ditolak.
- Edge menerapkan kontrol akses berbasis URI (lingkungan, proxy API, dan jalur URI) berdasarkan setelan produk API, beserta setelan Kuota.