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

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

В этом разделе описывается, как использовать 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"}'
}

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

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

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

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

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

  По умолчанию отображаются только монетизированные API-продукты (то есть API-продукты, имеющие хотя бы один опубликованный тарифный план). Чтобы отобразить все API-продукты, установите параметр запроса monetized в значение false . Это эквивалентно отправке GET-запроса к API-интерфейсу списка немонетизированных 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 , и определяет подмножество атрибутов монетизации с помощью 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-продукт в приложение:

$ 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 тип утверждения ключей, ключи потребителей должны быть утверждены явно. Явное утверждение ключей можно выполнить с помощью функции «Утвердить или отозвать определенный ключ» в 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 приложения разработчика :

$ 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 .
• Операция «VerifyAccessToken» в OAuthV1: проверяет подпись, подтверждает токен доступа OAuth 1.0a и «ключ потребителя», а также сопоставляет приложение с продуктом API. Дополнительную информацию см. в политике OAuth v1.0a .
• Операция «VerifyAccessToken» в OAuthV2: проверяет действительность токена доступа 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-продукта, а также настроек квот.