Публикация API с помощью Edge API

Вы просматриваете документацию Apigee Edge .
Перейдите к документации Apigee X. информация

В этом разделе описывается, как использовать Edge API для создания продуктов API для публикации на порталах разработчиков.

Создавайте продукты API с помощью API

Продукты API позволяют разработчикам регистрировать приложения, использующие API, с помощью ключей API и токенов доступа OAuth. Продукты API предназначены для того, чтобы вы могли «объединять» ресурсы API, а затем публиковать эти пакеты для различных групп разработчиков. Например, вам может потребоваться опубликовать один набор ресурсов API для разработчиков-партнеров, а другой пакет — для внешних разработчиков. Продукты API позволяют выполнять такое объединение «на лету», не требуя внесения каких-либо изменений в сами API. Дополнительным преимуществом является то, что доступ разработчика можно «обновлять» и «понижать», не требуя от разработчиков получения новых потребительских ключей для своих приложений.

Чтобы создать продукт API с использованием API, отправьте запрос POST к /organizations/ {org_name} /apiproducts . Дополнительные сведения см. в разделе Справочник по API создания продуктов API .

Следующий запрос создает продукт API под названием weather_free . Продукт API обеспечивает доступ ко всем API, предоставляемым прокси-сервером API, называемым weatherapi , который развернут в test среде. Тип утверждения установлен на auto что указывает на то, что любой запрос на доступ будет одобрен.

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 

Пример ответа:

{
  "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" : [ ]
}

Продукт API, созданный выше, реализует самый простой сценарий, разрешающий запросы к прокси-серверу API в среде. Он определяет продукт API, который позволяет авторизованному приложению получать доступ к любым ресурсам API, доступ к которым осуществляется через прокси-сервер API, работающий в тестовой среде. Продукты API предоставляют дополнительные параметры конфигурации, которые позволяют настраивать контроль доступа к вашим API для различных групп разработчиков. Например, вы можете создать два продукта API, которые предоставляют доступ к разным прокси-серверам API. Вы также можете создать два продукта API, которые предоставляют доступ к одним и тем же прокси-серверам API, но с разными связанными настройками квот.

Параметры конфигурации продукта API

Продукты API предоставляют следующие параметры конфигурации:

Ниже приведен более подробный пример создания продукта 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

Пример ответа

{
  "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"}'
}

Об областях применения

Область действия — это концепция, взятая из OAuth и примерно соответствующая концепции «разрешения». В Apigee Edge области действия совершенно необязательны. Вы можете использовать области для более детальной авторизации. Каждый потребительский ключ, выданный приложению, связан с «главной областью». Основная область действия — это набор всех областей действия во всех продуктах API, для которых приложение было одобрено. Для приложений, одобренных для использования нескольких продуктов API, основная область действия — это объединение всех областей, определенных в продуктах API, для которых утвержден потребительский ключ.

Посмотреть продукты API

Чтобы просмотреть продукты API, созданные для организации, использующей API, см. следующие разделы:

• Просмотреть продукты API (монетизируемые)

  По умолчанию отображаются только монетизируемые продукты API (то есть продукты API, у которых есть хотя бы один опубликованный тарифный план). Чтобы отобразить все продукты API, установите для параметра monetized запроса значение false . Это эквивалентно отправке запроса GET к API немонетизированных продуктов List API: https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts?expand=true .

• Просмотр продуктов API (немонетизируемых)
• Просмотр подходящих продуктов API для разработчика
• Просмотр подходящих продуктов API для компании

Ниже приведен пример просмотра продуктов API с помощью API:

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

Ответ должен выглядеть примерно так (показана только часть ответа):

{
  "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
}

Регистрация разработчиков с помощью API

Все приложения принадлежат либо разработчикам, либо компаниям. Поэтому, чтобы создать приложение, сначала необходимо зарегистрировать разработчика или компанию.

Разработчики регистрируются в организации путем создания профиля. Обратите внимание, что адрес электронной почты разработчика, включенный в профиль, используется в качестве уникального ключа разработчика в Apigee Edge.

Для поддержки монетизации необходимо определить атрибуты монетизации при создании или редактировании разработчиков. Вы также можете определить другие произвольные атрибуты для использования в пользовательской аналитике, применении настраиваемой политики и т. д.; эти произвольные атрибуты не будут интерпретироваться Apigee Edge,

Например, следующий запрос регистрирует профиль разработчика с адресом электронной почты ntesla@theremin.com и определяет подмножество атрибутов монетизации с помощью 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 

Пример ответа

{
          "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"
        }

Регистрация приложений для разработчиков с помощью API

Каждое приложение, зарегистрированное в Apigee Edge, связано с разработчиком и продуктом API. Когда приложение регистрируется от имени разработчика, Apigee Edge генерирует «учетные данные» (пару потребительского ключа и секрета), идентифицирующие приложение. Затем приложение должно передавать эти учетные данные как часть каждого запроса к продукту 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 используется некоторыми типами грантов OAuth (например, кодом авторизации) для проверки запросов на перенаправление из приложения. Если вы используете OAuth, то для этого значения должно быть установлено то же значение, что и для redirect_uri используемого для выполнения запросов OAuth.

Атрибут keyExpiresIn указывает в миллисекундах срок действия потребительского ключа, который будет создан для приложения разработчика. Значение по умолчанию -1 указывает на бесконечный период действия.

Пример ответа

{
  "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"
}

Управляйте потребительскими ключами для приложений с помощью API

Получите потребительский ключ (ключ API) для приложения.

Учетные данные для приложения (продукт API, потребительский ключ и секрет) возвращаются как часть профиля приложения. Администратор организации может получить потребительский ключ в любое время.

В профиле приложения отображается значение потребительского ключа и секрета, состояние потребительского ключа, а также любые ассоциации продуктов API для ключа. Как администратор, вы можете получить профиль ключа потребителя в любое время с помощью 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

Пример ответа

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

Дополнительные сведения см . в разделе «Получение ключевых сведений о приложении разработчика» .

Добавьте продукт API в приложение и ключ.

Чтобы обновить приложение и добавить новый продукт API, вы фактически добавляете продукт API в ключ приложения с помощью API-интерфейса «Добавить продукт API в ключ» . Дополнительную информацию см. в разделе Добавление продукта API в ключ .

Добавление продукта API к ключу приложения позволяет приложению, содержащему ключ, получать доступ к ресурсам API, включенным в продукт API. Следующий вызов метода добавляет в приложение новый продукт API:

$ 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 

Пример ответа:

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

Утвердить потребительские ключи

Установка типа утверждения вручную позволяет вам контролировать, какие разработчики могут получить доступ к ресурсам, защищенным продуктами API. Если в продуктах API для одобрения ключей установлено значение manual , потребительские ключи должны быть явно утверждены. Ключи можно явно утвердить с помощью Approve или Revoke Special Key of Developer App 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

Пример ответа

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

Дополнительную информацию см . в разделе «Утвердить или отозвать определенный ключ приложения разработчика» .

Утвердить продукты API для потребительских ключей

Ассоциация продукта API с потребительским ключом также имеет статус. Чтобы доступ к API был успешным, потребительский ключ должен быть одобрен, а потребительский ключ должен быть одобрен для соответствующего продукта API. Ассоциацию потребительского ключа с продуктом API можно утвердить с помощью API «Утвердить или отозвать продукт API для ключа для 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

Эта команда cURL не возвращает ответ. Дополнительные сведения см . в разделе «Утверждение или отзыв продукта API для ключа для приложения разработчика» .

Отзыв продуктов API для потребительских ключей

Существует множество причин, по которым вам может потребоваться отменить связь потребительского ключа с продуктом API. Вам может потребоваться удалить продукт API из потребительского ключа из-за неуплаты разработчиком, истечения пробного периода или перехода приложения с одного продукта API на другой.

Чтобы отменить связь потребительского ключа с продуктом API, используйте 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=revoke" \
-u email:password

Эта команда cURL не возвращает ответ. Дополнительную информацию см . в разделе «Утвердить или отозвать определенный ключ приложения разработчика» .

Принудительно использовать настройки продукта API

Чтобы продукты API применялись принудительно, к потоку прокси API должен быть прикреплен один из следующих типов политики:

• VerifyAPIKey: принимает ссылку на ключ API, проверяет, что он представляет собой допустимое приложение и соответствует продукту API. Дополнительную информацию см. в разделе «Проверка политики ключа API» .
• OAuthV1, операция «VerifyAccessToken»: проверяет подпись, проверяет токен доступа OAuth 1.0a и «ключ потребителя» и сопоставляет приложение с продуктом API. Дополнительную информацию см. в политике OAuth v1.0a .
• OAuthV2, операция «VerifyAccessToken»: проверяет действительность токена доступа OAuth 2.0, сопоставляет токен с приложением, проверяет действительность приложения, а затем сопоставляет приложение с продуктом API. Дополнительную информацию см. на главной странице OAuth .

После настройки политик и продуктов API Apigee Edge выполняет следующий процесс:

1. Запрос принимается Apigee Edge и направляется на соответствующий прокси-сервер API.
2. Выполняется политика, которая проверяет ключ API или токен доступа OAuth, предоставленный клиентом.
3. Edge разрешает ключ API или токен доступа к профилю приложения.
4. Edge разрешает список (если есть) продуктов API, связанных с приложением.
5. Первый соответствующий продукт API используется для заполнения переменных квоты.
6. Если ни один продукт API не соответствует ключу API или токену доступа, запрос отклоняется.
7. Edge обеспечивает контроль доступа на основе URI (среда, прокси-сервер API и путь URI) на основе настроек продукта API, а также настроек квоты.