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

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

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

Подробнее о том, как получить ключевую информацию о приложении разработчика…

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

Чтобы добавить в приложение новый продукт API, нужно добавить его в ключ приложения с помощью Add API Product to Key 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"
 }

Как одобрить ключи потребителя

Если задать для типа одобрения значение manual (вручную), вы сможете контролировать, какие разработчики могут получить доступ к ресурсам, защищенным продуктами API. Если для продуктов API задано одобрение ключа manual, потребительские ключи должны быть одобрены явным образом. Ключи можно явно одобрить с помощью API Approve or Revoke Specific Key of Developer App (Одобрить или отозвать определенный ключ приложения разработчика):

$ 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 Approve or Revoke API Product for a Key for a Developer App (Одобрить или отозвать продукт 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 Approve or Revoke Specific Key of Developer App , указав действие revoke для идентификатора клиента приложения разработчика:

$ 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 1.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, а также настройками квоты.