Implementa proxies de API mediante la API

Estás viendo la documentación de Apigee Edge.
Consulta la documentación de Apigee X.

Cada organización tiene un ciclo de vida de desarrollo de software (SDLC) único. A menudo, es necesario sincronizar y alinear la implementación del proxy de API con los procesos que se usan para los servicios de backend.

Los métodos de la API de Edge que se muestran en este tema se pueden usar para integrar la administración del proxy de API en el SDLC de tu organización. Un uso común de esta API es escribir secuencias de comandos o código que implementen proxies de API, o que migren proxies de API de un entorno a otro, como parte de un proceso automatizado más grande que también implementa o migra otras aplicaciones.

La API de Edge no hace suposiciones sobre tu SDLC (o la de otra persona, para el caso). En su lugar, expone funciones atómicas que tu equipo de desarrollo puede coordinar para automatizar y optimizar el ciclo de vida del desarrollo de la API.

Para obtener información completa, consulta API de Edge.

Para usar la API de Edge, debes autenticarte en tus llamadas. Puedes hacerlo con uno de los siguientes métodos:

Este tema se centra en el conjunto de APIs que se usan para administrar proxies de API.

Video: Mire este video breve para obtener información sobre cómo implementar una API.

Interactúa con la API

En los siguientes pasos, se te guiará por interacciones simples con las API.

Enumerar las API de tu organización

Puedes comenzar con la lista de todos los proxies de API de tu organización. (Recuerda sustituir las entradas por EMAIL:PASSWORD y ORG_NAME. Para obtener instrucciones, consulta Cómo usar la API de Edge.

curl -u EMAIL:PASSWORD \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis

Respuesta de muestra:

[ "weatherapi" ]

Obtén una API

Puedes llamar al método GET en cualquier proxy de API en tu organización. Esta llamada muestra una lista de todas las revisiones disponibles del proxy de API.

curl -u EMAIL:PASSWORD -H "Accept: application/json" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi

Respuesta de muestra:

{
  "name" : "weatherapi",
  "revision" : [ "1" ]
}

El único detalle que muestra este método es el nombre del proxy de API junto con la revisión asociada, que tiene un número asociado. Los proxies de API consisten en un conjunto de archivos de configuración. Las revisiones proporcionan un mecanismo liviano para administrar las actualizaciones de la configuración a medida que iteras. Las revisiones están numeradas de forma secuencial, lo que te permite revertir un cambio mediante la implementación de una revisión anterior del proxy de API. Además, puedes implementar una revisión de un proxy de API en el entorno de producción y, al mismo tiempo, crear revisiones nuevas de ese proxy de API en el entorno de prueba. Cuando estés listo, puedes promover la revisión superior del proxy de API en el entorno de pruebas con la revisión anterior del proxy de API en el entorno de producción.

En este ejemplo, solo hay una revisión porque se acaba de crear el proxy de API. A medida que un proxy de API recorre el ciclo de vida de la implementación y configuración iterativas, el número de revisión aumenta por números enteros. Con las llamadas directas a la API para implementar, tienes la opción de aumentar el número de revisión del proxy de API. A veces, cuando realizas cambios menores, es posible que no quieras aumentar la revisión.

Obtener revisión de la API

La versión de la API (por ejemplo, api.company.com/v1) debería cambiar con poca frecuencia. Cuando aumentas la versión de la API, les indicas a los desarrolladores que hubo un cambio significativo en la firma de la interfaz externa expuesta por la API.

La revisión del proxy de API es un número incrementado asociado con una configuración de proxy de API. Los servicios de API mantienen las revisiones de tus configuraciones para que puedas revertir una configuración cuando algo salga mal. De forma predeterminada, la revisión de un proxy de API aumenta automáticamente cada vez que importas un proxy de API mediante la API de importación de un proxy de API. Si no quieres que se aumente la revisión de un proxy de API, usa la API de actualización de revisiones del proxy de la API. Si usas Maven para realizar la implementación, usa las opciones clean o update, como se describe en el archivo readme del complemento de Maven.

Por ejemplo, puedes llamar al método GET en la revisión 1 del proxy de la API para obtener una vista detallada.

curl -u EMAIL:PASSWORD -H "Accept:application/json" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi/revisions/1

Respuesta de muestra

{
  "configurationVersion" : {
    "majorVersion" : 4,
    "minorVersion" : 0
  },
  "contextInfo" : "Revision 1 of application weatherapi, in organization {org_name}",
  "createdAt" : 1343178905169,
  "createdBy" : "andrew@apigee.com",
  "lastModifiedAt" : 1343178905169,
  "lastModifiedBy" : "andrew@apigee.com",
  "name" : "weatherapi",
  "policies" : [ ],
  "proxyEndpoints" : [ ],
  "resources" : [ ],
  "revision" : "1",
  "targetEndpoints" : [ ],
  "targetServers" : [ ],
  "type" : "Application"
}

Estos elementos de configuración del proxy de la API se documentan en detalle en la referencia de configuración del proxy de API.

Implementar una API en un entorno

Una vez que el proxy de API esté configurado para recibir y reenviar solicitudes de forma adecuada, puedes implementarlo en uno o más entornos. Por lo general, debes iterar en los proxies de API en test y, cuando esté listo, promover la revisión del proxy de API a prod. A menudo, descubrirás que tienes muchas más revisiones de un proxy de API en el entorno de pruebas, principalmente porque habrás mucho menos iteraciones en el entorno de producción.

No se puede invocar un proxy de API hasta que se haya implementado en un entorno. Una vez que implementes la revisión del proxy de la API en producción, puedes publicar la URL prod para los desarrolladores externos.

Cómo crear una lista de entornos

Cada organización en Apigee Edge tiene al menos dos entornos: test y prod. La distinción es arbitraria. El objetivo es brindarte un área para verificar que el proxy de API funcione correctamente antes de abrirlos para desarrolladores externos.

Cada entorno es en realidad solo una dirección de red, lo que te permite segregar el tráfico entre los proxies de API en los que estás trabajando y los que acceden las apps en el tiempo de ejecución.

Los entornos también proporcionan segregación de datos y recursos. Por ejemplo, puedes configurar diferentes cachés en prueba y producción, a las que solo pueden acceder los proxies de API que se ejecutan en ese entorno.

Ver entornos de una organización

curl -u EMAIL:PASSWORD \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments

Respuesta de ejemplo

[ "test", "prod" ]

Explora las implementaciones

Una implementación es una revisión de un proxy de API que se implementó en un entorno. Se puede acceder a un proxy de API que está en el estado implementado a través de la red, en las direcciones definidas en el elemento <VirtualHost> para ese entorno.

Implementa proxies de API

Los proxies de API no se pueden invocar hasta que se hayan implementado. Los servicios de API exponen las API de RESTful que proporcionan control sobre el proceso de implementación.

Solo se puede implementar una revisión de un proxy de API en un entorno a la vez. Por lo tanto, se debe anular la implementación de la revisión implementada. Puedes controlar si el nuevo paquete se implementa como una revisión nueva o si reemplaza la revisión existente.

Estás viendo la documentación de Apigee Edge.
Consulta la documentación de Apigee X.

Primero, anula la implementación de la revisión existente. Especifica el nombre del entorno y el número de revisión del proxy de API que quieres anular.

curl -X DELETE \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments \
  -u EMAIL:PASSWORD

Luego, implementa la revisión nueva. La nueva revisión del proxy de API ya debe existir:

curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments \
  -u EMAIL:PASSWORD

Implementación continua (cero tiempo de inactividad)

Para minimizar el potencial de tiempo de inactividad durante la implementación, usa el parámetro override en el método de implementación y establécelo en true.

No se puede implementar una revisión de un proxy de API por encima de otra. Siempre se debe anular la implementación de la primera. Si configuras override como true, indicas que una revisión de un proxy de API debe implementarse sobre la revisión implementada actualmente. El resultado es que la secuencia de implementación se revierte, la revisión nueva se implementa y, una vez que se completa la implementación, se anula la revisión ya implementada.

En el siguiente ejemplo, se configura el valor override pasándolo como un parámetro de formulario:

curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/e/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments" \
  -d "override=true" \
  -u EMAIL:PASSWORD

Puedes optimizar aún más la implementación si configuras el parámetro delay. El parámetro delay especifica un intervalo de tiempo, en segundos, antes del cual se debería anular la implementación de la revisión anterior. El efecto es que las transacciones en tránsito tienen un intervalo en el cual se debe completar antes de que se anule la implementación del proxy de API que procesa la transacción. A continuación, se muestra lo que sucede con override=true y el parámetro delay configurado:

  • La revisión 1 controla solicitudes.
  • Se está implementando la revisión 2 en paralelo.
  • Cuando la Revisión 2 está completamente implementada, el tráfico nuevo se envía a la Revisión 2. No se envía tráfico nuevo a la Revisión 1.
  • Sin embargo, es posible que la Revisión 1 aún esté procesando transacciones existentes. Si configuras el parámetro delay (por ejemplo, 15 segundos), le darás a la Revisión 1 15 segundos para terminar de procesar las transacciones existentes.
  • Después del intervalo de retraso, se anula la implementación de la revisión 1.
curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/e/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments?delay=15" \
  -d "override=true" \
  -u EMAIL:PASSWORD
Parámetro de consulta Descripción
override

El valor predeterminado es false (comportamiento de implementación normal: la revisión existente no se implementa; luego, se implementa la revisión nueva).

Configúralo en true para anular el comportamiento de implementación normal y proporcionar una implementación sin interrupciones. La revisión existente permanece implementada mientras la revisión nueva también se implementa. Cuando se implementa la revisión nueva, se anula la implementación de la anterior. Se usa junto con el parámetro delay para controlar cuándo se produce la anulación de la implementación.

delay

Para permitir que se complete el procesamiento de transacciones en la revisión existente antes de que se anule la implementación, y para eliminar la posibilidad de 502 Bad Gateway o 504 Gateway Timeout errors, establece este parámetro en la cantidad de segundos que deseas que se retrase la implementación. No hay límite para la cantidad de segundos que puedes configurar y no hay consecuencias en el rendimiento si configuras una gran cantidad de segundos. Durante la demora, no se envía tráfico nuevo a la revisión anterior.

El valor predeterminado es 0 (cero) segundos. Cuando override se establece como verdadero y delay es 0, se anula la implementación de la revisión existente inmediatamente después de que se implementa la revisión nueva. Los valores negativos se tratan como 0 (cero) segundos.

Cuando se usa override=true junto con un delay, se pueden eliminar las respuestas 5XX de HTTP durante la implementación. Esto se debe a que ambas revisiones del proxy de API se implementarán de forma simultánea, y la revisión anterior se anulará después del retraso.

Ver todas las implementaciones de una revisión de la API

A veces, es necesario recuperar una lista de todas las revisiones implementadas actualmente de un proxy de API.

curl https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi/revisions/1/deployments \
  -u EMAIL:PASSWORD
{
  "aPIProxy" : "weatherapi",
  "environment" : [ {
    "configuration" : {
      "basePath" : "",
      "steps" : [ ]
    },
    "name" : "test",
    "server" : [ {
      "status" : "deployed",
      "type" : [ "message-processor" ],
      "uUID" : "90096dd1-1019-406b-9f42-fbb80cd01200"
    }, {
      "status" : "deployed",
      "type" : [ "message-processor" ],
      "uUID" : "7d6e2eb1-581a-4db0-8045-20d9c3306549"
    }, {
      "status" : "deployed",
      "type" : [ "router" ],
      "uUID" : "1619e2d7-c822-45e0-9f97-63882fb6a805"
    }, {
      "status" : "deployed",
      "type" : [ "router" ],
      "uUID" : "8a5f3d5f-46f8-4e99-b4cc-955875c8a8c8"
    } ],
    "state" : "deployed"
  } ],
  "name" : "1",
  "organization" : "org_name"
}

La respuesta anterior contiene muchas propiedades específicas de la infraestructura interna de Apigee Edge. A menos que use Apigee Edge de forma local, no puede cambiar esta configuración.

Las propiedades importantes que se incluyen en la respuesta son organization, environment, aPIProxy, name y state. Si revisas estos valores de propiedad, puedes confirmar que se implemente una revisión específica de un proxy de API en un entorno.

Ver todas las implementaciones en el entorno de pruebas

También puedes recuperar el estado de implementación de un entorno específico (incluido el número de revisión del proxy de API implementado actualmente) mediante la siguiente llamada:

curl -u EMAIL:PASSWORD
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/test/deployments

Esto muestra el mismo resultado que el anterior para cada API implementada en el entorno de prueba.

Ver todas las implementaciones en tu organización

Para recuperar una lista de todas las revisiones implementadas actualmente de todos los proxies de API en todos los entornos, usa el siguiente método de API:

curl https://api.enterprise.apigee.com/v1/o/ORG_NAME/deployments \
  -u EMAIL:PASSWORD

Esto muestra el mismo resultado anterior para todos los proxies de API implementados en todos los entornos.

Dado que la API es RESTful, puedes usar el método POST, junto con una carga útil JSON o XML, en el mismo recurso para crear un proxy de API.

Se generará un perfil para su proxy de API. La representación predeterminada de un proxy de API está en la notación de objetos JavaScript (JSON). A continuación, se muestra la respuesta JSON predeterminada a la solicitud POST anterior, que creó un proxy de API llamado weatherapi. A continuación, se incluye una descripción de cada elemento del perfil:

{
  "configurationVersion" : {
    "majorVersion" : 4,
    "minorVersion" : 0
  },
  "contextInfo" : "Revision 1 of application weatherapi, in organization {org_name}",
  "createdAt" : 1357172145444,
  "createdBy" : "you@yourcompany.com",
  "displayName" : "weatherapi",
  "lastModifiedAt" : 1357172145444,
  "lastModifiedBy" : "you@yourcompany.com",
  "name" : "weatherapi",
  "policies" : [ ],
  "proxyEndpoints" : [ ],
  "resources" : [ ],
  "revision" : "1",
  "targetEndpoints" : [ ],
  "targetServers" : [ ],
  "type" : "Application"
}

El perfil de proxy de API que se genera demuestra la estructura completa de un proxy de API:

  • APIProxy revision: la iteración numerada secuencialmente de la configuración del proxy de API, como la mantienen los servicios de API
  • APIProxy name: El nombre único del proxy de API
  • ConfigurationVersion: Es la versión de los servicios de API a la que cumple la configuración del proxy de API.
  • CreatedAt: La hora en la que se generó el proxy de API, en formato UNIX
  • CreatedBy: Es la dirección de correo electrónico del usuario de Apigee Edge que creó el proxy de API.
  • DisplayName: Un nombre fácil de usar para el proxy de API
  • LastModifiedAt: La hora en la que se generó el proxy de API, en formato UNIX
  • LastModifiedBy: Es la dirección de correo electrónico del usuario de Apigee Edge que creó el proxy de API.
  • Policies: Una lista de las políticas que se agregaron a este proxy de API
  • ProxyEndpoints: Una lista de ProxyEndpoints con nombre
  • Resources: Una lista de recursos (JavaScript, Python, Java, XSLT) disponibles para su ejecución en este proxy de API
  • TargetServers: Una lista de TargetServers con nombre (que se pueden crear mediante la API de administración), que se usa en configuraciones avanzadas para fines de balanceo de cargas
  • TargetEndpoints: Una lista de TargetEndpoints con nombre

Ten en cuenta que muchos de los elementos de la configuración del proxy de API creados mediante el método POST simple anterior están vacíos. En los siguientes temas, aprenderás a agregar y configurar los componentes clave de un proxy de API.

También puedes leer sobre estos elementos de configuración en la referencia de configuración del proxy de API.

Secuencias de comandos con la API

Usa los proxies de API de muestra, disponibles en GitHub, para proporcionar secuencias de comandos de shell que unen la herramienta de implementación de Apigee. Si por algún motivo no puedes usar la herramienta de implementación de Python, puedes llamar directamente a la API. Ambos enfoques se muestran en las secuencias de comandos de ejemplo que aparecen a continuación.

Une la herramienta de implementación

Primero, asegúrate de que la herramienta de implementación de Python esté disponible en tu entorno local.

Luego, crea un archivo que contenga tus credenciales. Las secuencias de comandos de implementación que escribas importarán esta configuración, lo que te ayudará a administrar de forma centralizada las credenciales de tu cuenta. En la muestra de la plataforma de API, este archivo se llama setenv.sh.

#!/bin/bash

org="Your ORG on enterprise.apigee.com"
username="Your USERNAME on enterprise.apigee.com"

# While testing, it's not necessary to change the setting below
env="test"
# Change the value below only if you have an on-premise deployment
url="https://api.enterprise.apigee.com"
# Change the value below only if you have a custom domain
api_domain="apigee.net"

export org=$org
export username=$username
export env=$env
export url=$url
export api_domain=$api_domain

El archivo anterior hace que toda tu configuración esté disponible para las secuencias de comandos de shell que unen la herramienta de implementación.

Ahora cree una secuencia de comandos de shell que importe esa configuración y la use para llamar a la herramienta de implementación. (Para ver un ejemplo, consulta muestras de la plataforma de API de Apigee).

#!/bin/bash

source path/to/setenv.sh

echo "Enter your password for the Apigee Enterprise organization $org, followed by [ENTER]:"

read -s password

echo Deploying $proxy to $env on $url using $username and $org

path/to/deploy.py -n {api_name} -u $username:$password -o $org -h $url -e $env -p / -d path/to/apiproxy

A fin de facilitarte la vida, crea una secuencia de comandos para invocar y probar la API de la siguiente manera:

#!/bin/bash

echo Using org and environment configured in /setup/setenv.sh

source /path/to/setenv.sh

set -x

curl "http://$org-$env.apigee.net/{api_basepath}"

Invoca la API directamente

Puede ser útil escribir secuencias de comandos de shell simples que automaticen el proceso de carga y de implementación de proxies de API.

La siguiente secuencia de comandos invoca directamente la API de administración. Anula la implementación de la revisión existente del proxy de API que estás actualizando, crea un archivo ZIP del directorio /apiproxy que contiene tus archivos de configuración de proxy y, luego, sube, importa e implementa la configuración.

#!/bin/bash

#This sets the name of the API proxy and the basepath where the API will be available
api=api

source /path/to/setenv.sh

echo Delete the DS_store file on OSX

echo find . -name .DS_Store -print0 | xargs -0 rm -rf
find . -name .DS_Store -print0 | xargs -0 rm -rf

echo "Enter your password for the Apigee Enterprise organization $org, followed by [ENTER]:"

read -s password

echo Undeploy and delete the previous revision

# Note that you need to explicitly update the revision to be undeployed.
# One benefit of the Python deploy tool is that it manages this for you.

curl -k -u $username:$password "$url/v1/o/$org/e/$env/apis/$api/revisions/1/deployments" -X DELETE

curl -k -u $username:$password -X DELETE "$url/v1/o/$org/apis/$api/revisions/1"

rm -rf $api.zip

echo Create the API proxy bundle and deploy

zip -r $api.zip apiproxy

echo Import the new revision to $env environment 

curl -k -v -u $username:$password "$url/v1/o/$org/apis?action=import&name=$api" -T $api.zip -H "Content-Type: application/octet-stream" -X POST

echo Deploy the new revision to $env environment 

curl -k -u $username:$password "$url/v1/o/$org/e/$env/apis/$api/revisions/1/deployments" -X POST