Estás consultando la documentación de Apigee Edge.
Consulta la
documentación de Apigee X. Información
En esta sección, se describe cómo usar la API de Edge a fin de crear productos de API que se publicarán en portales para desarrolladores.
Crea productos de API con la API
Los productos de API permiten a los desarrolladores registrar aplicaciones que consumen API mediante claves de API y tokens de acceso de OAuth. Los productos de API están diseñados para permitirte “agrupar” recursos de API y, luego, publicarlos en diferentes grupos de desarrolladores. Por ejemplo, es posible que debas publicar un conjunto de recursos de API para tus desarrolladores socios y, al mismo tiempo, publicar otro paquete para desarrolladores externos. Los productos de API te permiten realizar esta agrupación sobre la marcha, sin necesidad de realizar cambios en tus APIs. Un beneficio adicional es que el acceso de los desarrolladores puede “actualizarse” o “cambiar a una versión inferior” sin necesidad de que los desarrolladores obtengan claves de consumidor nuevas para sus apps.
Para crear un producto de API con la API, emite una solicitud POST a /organizations/{org_name}/apiproducts
.
Para obtener más información, consulta la referencia de la API de Create API Product.
La siguiente solicitud crea un producto de API llamado weather_free
. El producto de API proporciona acceso a todas las API que expone el proxy de API llamado weatherapi
que se implementa en el entorno test
. El tipo de aprobación se establece en auto
, lo que indica que se aprobará cualquier solicitud de acceso.
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
Respuesta de muestra:
{ "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" : [ ] }
El producto de API creado anteriormente implementa la situación más básica, la autorización de solicitudes a un proxy de API en un entorno. Define un producto de API que permite que una app autorizada acceda a cualquier recurso de API a los que se accede a través del proxy de API que se ejecuta en el entorno de pruebas. Los productos de API exponen parámetros de configuración adicionales que te permiten personalizar el control de acceso a tus APIs para diferentes grupos de desarrolladores. Por ejemplo, puedes crear dos productos de API que proporcionen acceso a proxies de API diferentes. También puedes crear dos productos de API que proporcionen acceso a los mismos proxies de API, pero con una configuración de cuota asociada diferente.
Opciones de configuración de los productos de API
Los productos de API exponen las siguientes opciones de configuración:
Nombre | Descripción | Predeterminada | ¿Es obligatorio? |
---|---|---|---|
apiResources |
Una lista separada por comas de URI, o rutas de recursos, “agrupadas”en el producto de API. De forma predeterminada, las rutas de acceso a los recursos se asignan desde la variable Puedes seleccionar una ruta de acceso específica o seleccionar todas las rutas secundarias con un comodín.
Se admiten comodines (/** y /*). El comodín de asterisco doble indica que se incluyen todos los subURI. Un solo asterisco indica que solo se incluyen los URI de un nivel inferior. |
No disponible | No |
approvalType |
Especifica el modo en que se aprueban las claves de API para acceder a las APIs definidas por el producto de API. Si se configura como manual , la clave que se genera para la app se encuentra en el estado "pendiente".
Esas claves no funcionarán hasta que se hayan aprobado de forma explícita. Si se configura como auto , todas las claves se generan en “aprobada” y funcionan de inmediato. (auto normalmente se usa para proporcionar acceso a productos de API gratuitos o de prueba que proporcionan cuotas o capacidades limitadas). |
No disponible | Sí |
attributes |
Es el array de atributos que se pueden usar para extender el perfil de producto de la API predeterminado con metadatos específicos del cliente.
Usa esta propiedad para especificar el nivel de acceso del producto de API como public, private o internal. Por ejemplo:
"atributos": [
{
"name": "acceso",
"value": "public"
}:
{
"name": "foo","value": "foo" }, { "name": "bar", "value": "bar" }
]
|
No disponible | No |
scopes |
Una lista separada por comas de los permisos de OAuth que se validan en el entorno de ejecución. (Apigee Edge valida que los permisos de cualquier token de acceso presentado coincidan con el alcance establecido en el producto de API). | No disponible | No |
proxies |
Proxies de API con nombre a los que está vinculado este producto de API. Cuando especificas proxies, puedes asociar recursos en el producto de API con proxies de API específicos, lo que evita que los desarrolladores accedan a esos recursos a través de otros proxies de API. | No disponible | No. Si no se define, apiResources debe definirse de forma explícita (consulta la información sobre apiResources anterior) y la variable flow.resource.name configurada en la política AssignMessage. |
environments |
Son entornos con nombre (por ejemplo, “prueba” o “prod”) a los que está vinculado este producto de API. Cuando especificas uno o más entornos, puedes vincular los recursos enumerados en el producto de API a un entorno específico, lo que evita que el desarrollador acceda a esos recursos a través de proxies de API en otro entorno. Esta configuración se usa, por ejemplo, para evitar que los proxies de API implementados en “test” accedan a los recursos asociados con los proxies de API en “prod”. | No disponible | No. Si no está definido, se debe definir apiResources de forma explícita, y la variable flow.resource.name está establecida en la política AssignMessage. |
quota |
Cantidad de solicitudes permitidas por app durante el intervalo de tiempo especificado | No disponible | No |
quotaInterval |
Cantidad de unidades de tiempo en las que se evalúan las cuotas | No disponible | No |
quotaTimeUnit |
La unidad de tiempo (minuto, hora, día o mes) sobre la que se cuentan las cuotas | No disponible | No |
A continuación, se proporciona un ejemplo más detallado para crear un producto de 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
Respuesta de muestra:
{ "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"}' }
Acerca de los permisos
Un alcance es un concepto extraído de OAuth y se mapea aproximadamente con el concepto de un "permiso". En Apigee Edge, los permisos son completamente opcionales. Puedes usar permisos para obtener una autorización más detallada. Cada clave de consumidor que se emite a una aplicación se asocia a un "permiso principal". El alcance principal es el conjunto de todos los alcances en todos los productos de API. En este caso, se aprobó la app. En el caso de las apps aprobadas para consumir varios productos de API, el alcance principal es la unión de todos los alcances definidos en los productos de API para los que se aprobó la clave de consumidor.
Visualiza productos de API
Si deseas ver los productos de API creados para una organización con la API, consulta las siguientes secciones:
- Ver productos de API (monetizados)
De forma predeterminada, solo se muestran productos de API monetizados (es decir, productos de API con al menos un plan de tarifas publicado). Para mostrar todos los productos de API, establece el parámetro de consulta
monetized
enfalse
. Esto equivale a emitir una solicitud GET a la API de productos de la API de List no monetizada:https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts?expand=true
- Visualiza productos de API (no monetizada)
- Consulta productos de API aptos para un desarrollador
- Consulta productos de API aptos para una empresa
A continuación, se proporciona un ejemplo de cómo visualizar los productos de API con la API:
curl -X GET "https://ext.apiexchange.org/v1/mint/organizations/{org_name}/products?monetized=true" \ -H "Accept:application/json" \ -u email:password
La respuesta debería ser similar a la siguiente (solo se muestra una parte):
{ "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 }
Registra desarrolladores con la API
Todas las apps pertenecen a desarrolladores o empresas. Por lo tanto, para crear una app, primero debes registrar un desarrollador o una empresa.
Los desarrolladores deben registrarse en una organización mediante la creación de un perfil. Ten en cuenta que el correo electrónico del desarrollador que se incluye en el perfil se usa como clave única para el desarrollador en todo Apigee Edge.
Para admitir la monetización, debes definir los atributos de monetización cuando crees o edites desarrolladores. También puedes definir otros atributos arbitrarios para usar en estadísticas personalizadas, aplicación de políticas personalizadas, etc.; estos atributos arbitrarios no serán interpretados por Apigee Edge.
Por ejemplo, la siguiente solicitud registra un perfil para un desarrollador cuya dirección de correo electrónico es ntesla@theremin.com
y define un subconjunto de atributos de monetización con la API de Create 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
Respuesta de ejemplo
{ "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" }
Registra apps de desarrollador con la API
Cada app registrada en Apigee Edge está asociada con un desarrollador y un producto de API. Cuando se registra una app en nombre de un desarrollador, Apigee Edge genera una “credencial” (un par clave y secreto del consumidor) que identifica la app. Luego, la app debe pasar esas credenciales como parte de cada solicitud a un producto de API asociado con la app.
La siguiente solicitud usa la API de Create Developer App a fin de registrar una app para el desarrollador que creaste anteriormente: ntesla@theremin.com. Cuando registras una app, defines un nombre para ella, una callbackUrl y una lista de uno o más productos de 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
Algunos tipos de permisos de OAuth (como el código de autorización) usan la callbackUrl para validar las solicitudes de redireccionamiento de la app. Si usas OAuth, este valor se debe establecer como el mismo valor que redirect_uri
, que se usa para realizar solicitudes OAuth.
El atributo keyExpiresIn
especifica, en milisegundos, durante la vida útil de la clave de consumidor que se generará para la app de desarrollador. El valor predeterminado, -1, indica un período de validez infinito.
Respuesta de ejemplo
{ "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" }
Administra claves de consumidores para apps mediante la API
Obtén la clave de consumidor (la clave de API) de la app
Las credenciales para una app (producto de API, clave de consumidor y secreto) se muestran como parte del perfil de la app. Un administrador de una organización puede recuperar la clave de consumidor en cualquier momento.
En el perfil de la app, se muestra el valor de la clave de consumidor y el secreto, el estado de la clave de consumidor y cualquier asociación de producto de la API de la clave. Como administrador, puedes recuperar el perfil de clave del consumidor en cualquier momento mediante Obtén información clave sobre una API de apps de desarrollador:
$ 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
Respuesta de muestra:
{ "apiProducts" : [ { "apiproduct" : "weather_free", "status" : "approved" } ], "attributes" : [ ], "consumerKey" : "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J", "consumerSecret" : "1eluIIdWG3JGDjE0", "status" : "approved" }
Para obtener más información, consulta Obtén información clave sobre una app de desarrollador.
Agrega un producto de API a una app y una clave
Para actualizar una app a fin de agregar un nuevo producto de API, debes agregar el producto de API a la clave de la app mediante Agrega el producto de API a la API de la clave. Consulta Agrega el producto de API a la clave para obtener más información.
Cuando se agrega un producto de API a una clave de app, la app que contiene la clave puede acceder a los recursos de API empaquetados en ese producto. La siguiente llamada de método agrega un nuevo producto de API a una app:
$ 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
Respuesta de muestra:
{ "apiProducts": [ { "apiproduct": "weather_free", "status": "approved" }, { "apiproduct": "newAPIProduct", "status": "approved" } ], "attributes": [], "consumerKey": "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J", "consumerSecret": "1eluIIdWG3JGDjE0", "expiresAt": -1, "issuedAt": 1411491156464, "scopes": [], "status": "approved" }
Aprueba claves de consumidor
Si configuras el tipo de aprobación como manual, podrás controlar qué desarrolladores pueden acceder a los recursos protegidos por los productos de API. Cuando la aprobación de claves de los productos de API está establecida en manual
, las claves de consumidor deben aprobarse de forma explícita. Se pueden aprobar explícitamente las claves con la API Aprobar o revocar clave específica de la app de desarrollador:
$ 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
Respuesta de muestra:
{ "apiProducts" : [ { "apiproduct" : "weather_free", "status" : "approved" } ], "attributes" : [ ], "consumerKey" : "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J", "consumerSecret" : "1eluIIdWG3JGDjE0", "status" : "approved" }
Para obtener más información, consulta Aprueba o revoca claves específicas de apps de desarrollador.
Aprueba productos de API para claves de consumidor
La asociación de un producto de API con una clave de consumidor también tiene un estado. A fin de que el acceso a la API sea exitoso, se debe aprobar la clave de consumidor y la clave de consumidor debe estar aprobada para el producto de API adecuado. La asociación de una clave de consumidor con un producto de API se puede aprobar usando la API Aprobar o revocar un producto de API para una clave para una app de desarrollador:
$ 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
En este comando cURL, no se muestra una respuesta. Consulta Aprueba o revoca el producto de API para una clave de app de desarrollador a fin de obtener más información.
Revoca productos de API para claves de consumidor
Existen muchos motivos por los que tal vez debas revocar la asociación de una clave de consumidor con un producto de API. Es posible que debas quitar un producto de API de una clave de consumidor debido a que el desarrollador no realizó el pago, a que venció el período de prueba o a que se promociona una app de un producto de API a otro.
Para revocar la asociación de una clave de consumidor con un producto de API, usa la API Aprueba o revoca la clave específica de la app de desarrollador mediante la acción de revocar contra la clave de consumidor de la app de desarrollador.
$ 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
En este comando cURL, no se muestra una respuesta. Para obtener más información, consulta Aprueba o revoca claves específicas de apps de desarrollador.
Aplica la configuración del producto de API
Para que se apliquen los productos de API, se debe adjuntar uno de los siguientes tipos de políticas al flujo de proxy de API:
- VerifyAPIKey: toma una referencia a una clave de API, verifica que representa una app válida y coincide con el producto de API. Consulta la política para verificar la clave de API para obtener más información.
- Operación OAuthV1, “VerifyAccessToken”: Verifica la firma, valida un token de acceso de OAuth 1.0a y una “clave de consumidor” y hace coincidir la app con el producto de API. Consulta la política OAuth v1.0a para obtener más información.
- OAuthV2, operación "VerifyAccessToken": verifica que el token de acceso de OAuth 2.0 sea válido, coincida con el token con la aplicación, verifica que la aplicación sea válida y, luego, asocia la aplicación con un producto de API. Consulta la página principal de OAuth para obtener más información.
Una vez que se configuran las políticas y los productos de API, Apigee Edge ejecuta el siguiente proceso:
- Apigee Edge recibe una solicitud y la enruta al proxy de API correspondiente.
- Se ejecuta una política que verifica la clave de API o el token de acceso de OAuth que presenta el cliente.
- Edge resuelve la clave de API o el token de acceso a un perfil de la app.
- Edge resuelve la lista (si existe) de productos de API asociados con la app.
- El primer producto de API que coincide se usa para propagar las variables de cuota.
- Si ningún producto de API coincide con la clave de API o el token de acceso, se rechaza la solicitud.
- Edge aplica el control de acceso basado en URI (entorno, proxy de API y ruta de URI) en función de la configuración del producto de la API, junto con la configuración de cuota.