Publica APIs con la API de Edge

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 proxy.pathsuffix. El sufijo de la ruta del proxy se define como el fragmento del URI que sigue la ruta base del proxy. Por ejemplo, en el siguiente producto de API de muestra, el elemento apiResources se define como /forecastrss. Dado que la ruta base definida para este proxy de API es /weather, significa que este producto de API solo permite solicitudes a /weather/forecastrss.

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.

De forma predeterminada, '/' admite los mismos recursos que “/**”, así como la ruta base definida por el proxy de API. Por ejemplo, si la ruta base del proxy de API es /v1/weatherapikey, entonces el producto de la API admite solicitudes a /v1/weatherapikey y a cualquier URI secundario, como /v1/weatherapikey/forecastrss, /v1/weatherapikey/region/CA, etc. Consulta Administra productos de API para obtener información sobre cómo cambiar el comportamiento de esta configuración predeterminada.

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
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:

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:

  1. Apigee Edge recibe una solicitud y la enruta al proxy de API correspondiente.
  2. Se ejecuta una política que verifica la clave de API o el token de acceso de OAuth que presenta el cliente.
  3. Edge resuelve la clave de API o el token de acceso a un perfil de la app.
  4. Edge resuelve la lista (si existe) de productos de API asociados con la app.
  5. El primer producto de API que coincide se usa para propagar las variables de cuota.
  6. Si ningún producto de API coincide con la clave de API o el token de acceso, se rechaza la solicitud.
  7. 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.