Implementa proxies de API con la API

Estás viendo la documentación de Apigee Edge.
Ir a la documentación de Apigee X. info

Cada organización tiene un ciclo de vida de desarrollo de software (SDLC) único. Por lo general, 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 de proxy de API en el SDLC de tu organización. Un uso común de esta API es escribir secuencias de comandos o códigos que implementan proxies de API, o que migran 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 realiza suposiciones acerca de tu SDLC (ni de nadie más). En cambio, exponen funciones atómicas que puede coordinar tu equipo de desarrollo para automatizar y optimizar el ciclo de vida de desarrollo de la API.

Para obtener información completa, consulta APIs 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: Mira este video corto para aprender a implementar una API.

Interactúa con la API

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

Enumera las APIs de tu organización

Para comenzar, puedes enumerar todos los proxies de API de tu organización. (Recuerda sustituir las entradas por EMAIL:PASSWORD y ORG_NAME. Para obtener instrucciones, consulta Usa 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 de 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 constan de un paquete 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 prod mientras continúas creando revisiones nuevas de ese proxy de API en el entorno test. Cuando estés listo, puedes promover la revisión más alta del proxy de API del entorno de pruebas a la revisión anterior del proxy de API en el entorno prod.

En este ejemplo, solo hay una revisión porque el proxy de API se acaba de crear. A medida que un proxy de API pasa por el ciclo de vida de la configuración y la implementación iterativas, el número de revisión aumenta en números enteros. Si usas llamadas directas a la API para implementar, puedes aumentar de forma opcional 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.

Obtén la revisión de la API

La versión de la API (por ejemplo, api.company.com/v1) debe cambiar con muy 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 aumentado asociado con una configuración de proxy de API. Los servicios de API mantienen revisiones de tus configuraciones para que puedas revertir una configuración cuando algo sale mal. De forma predeterminada, la revisión de un proxy de API se aumenta automáticamente cada vez que importas un proxy de API con la API de Importar un proxy de API. Si no quieres aumentar la revisión de un proxy de API, usa la API de Actualizar revisión del proxy de API. Si usas Maven para implementar, usa las opciones clean o update, como se describe en el archivo Léame del complemento de Maven.

Por ejemplo, puedes llamar al método GET en la revisión 1 del proxy de 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 API se documentan en detalle en la referencia de configuración del proxy de API.

Implementa una API en un entorno

Una vez que el proxy de API esté configurado para recibir y reenviar solicitudes correctamente, puedes implementarlo en uno o más entornos. Por lo general, iteras en proxies de API en test y, luego, cuando esté listo, promueves la revisión del proxy de API a prod. A menudo, verás que tienes muchas más revisiones de un proxy de API en el entorno de pruebas, principalmente porque harás mucha menos iteración en el entorno prod.

No se puede invocar un proxy de API hasta que se haya implementado en un entorno. Una vez que hayas implementado la revisión del proxy de API en prod, podrás publicar la URL de prod para desarrolladores externos.

Cómo enumerar entornos

Todas las organizaciones en Apigee Edge tienen al menos dos entornos: test y prod. La distinción es arbitraria. El objetivo es proporcionarte un área para verificar que tu proxy de API funcione correctamente antes de abrirlo a desarrolladores externos.

Cada entorno es solo una dirección de red, que te permite segregar el tráfico entre los proxies de API en los que trabajas y los que acceden a las apps en el entorno de ejecución.

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

Visualiza los entornos de una organización

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

Respuesta de muestra:

[ "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 se encuentra en el estado deployed a través de la red, en las direcciones definidas en el elemento <VirtualHost> para ese entorno.

Implementa proxies de API

No se pueden invocar proxies de API hasta que se hayan implementado. Los servicios de API exponen APIs 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 en un momento determinado. Por lo tanto se debe anular la implementación de la revisión implementada. Puedes controlar si el paquete nuevo se implementa como una revisión nueva o si reemplaza la revisión existente.

Estás viendo la documentación de Apigee Edge.
Ir a la documentación de Apigee X. info

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

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 revisión nueva 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 sin interrupciones (sin tiempo de inactividad)

Para minimizar la posibilidad de tiempo de inactividad durante la implementación, usa el parámetro override en el método de implementación y configúralo como true.

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

En el siguiente ejemplo, se establece el valor override pasando como 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 delay parámetro especifica un intervalo de tiempo, en segundos, antes del cual se debe anular la implementación de la revisión anterior. El efecto es que las transacciones en curso tienen un intervalo de tiempo en el que completarse antes de que se anule la implementación del proxy de API que procesa su transacción. A continuación, se muestra lo que sucede con override=true y el parámetro delay configurado:

  • La revisión 1 controla las solicitudes.
  • La revisión 2 se está implementando en paralelo.
  • Cuando la revisión 2 se implementa por completo, 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 delay parámetro (por ejemplo, 15 segundos), le das 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: se anula la implementación de la revisión existente y, luego, se implementa la revisión nueva).

Configúralo como true para anular el comportamiento de implementación normal y proporcionar una implementación sin interrupciones. La revisión existente permanece implementada mientras también se está implementando la revisión nueva. Cuando se implementa la revisión nueva, se anula la implementación de la revisión anterior. Úsalo 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 eliminar la posibilidad de 502 Bad Gateway o 504 Gateway Timeout errors), configura este parámetro en la cantidad de segundos que deseas que se retrase la anulación de la implementación. No hay límite para la cantidad de segundos que puedes configurar, y no hay consecuencias en el rendimiento por configurar una gran cantidad de segundos. Durante el retraso, no se envía tráfico nuevo a la revisión anterior.

El valor predeterminado es 0 (cero) segundos. Cuando override se establece en true 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 HTTP 5XX durante la implementación. Esto se debe a que ambas revisiones del proxy de API se implementarán de forma simultánea, y se anulará la implementación de la revisión anterior después del retraso.

Consulta todas las implementaciones de una revisión de 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 uses Apigee Edge On-Premises, no puedes cambiar esta configuración.

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

Consulta 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) con 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 pruebas.

Consulta todas las implementaciones de 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 que el anterior para todos los proxies de API implementados en todos los entornos.

Como 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 genera un perfil para tu proxy de API. La representación predeterminada de un proxy de API está en 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 muestra la estructura completa de un proxy de API:

  • APIProxy revision: La iteración numerada de forma secuencial de la configuración del proxy de API, según lo mantienen los servicios de API
  • APIProxy name: El nombre único del proxy de API
  • ConfigurationVersion: Versión de los servicios de API a la que se ajusta la configuración del proxy de API
  • CreatedAt: Hora en que se generó el proxy de API, con formato de hora UNIX
  • CreatedBy: 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: Hora en que se generó el proxy de API, con formato de hora UNIX
  • LastModifiedBy: Dirección de correo electrónico del usuario de Apigee Edge que creó el proxy de API
  • Policies: Una lista de 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 y XSLT) disponibles para ejecutarse en este proxy de API
  • TargetServers: Una lista de TargetServers con nombre (que se pueden crear con la API de Management), que se usan 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 con 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.

Crea secuencias de comandos en la API

El uso de los proxies de API de muestra, disponibles en GitHub, proporciona secuencias de comandos que encapsulan la herramienta de implementación de Apigee. Si por algún motivo no puedes usar la herramienta de implementación de Python, puedes llamar a la API directamente. Ambos enfoques se muestran en las siguientes secuencias de comandos de muestra.

Encapsula 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 para contener 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 todos tus parámetros de configuración estén disponibles para las secuencias de comandos que encapsulan la herramienta de implementación.

Ahora, crea una secuencia de comandos de shell que importe esos parámetros de configuración y los use para llamar a la herramienta de implementación. (Para obtener un ejemplo, consulta Ejemplos 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

Para que tu vida sea más fácil, también 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 directamente la API

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

La siguiente secuencia de comandos invoca directamente la API de Management. Anula la implementación de la revisión existente de el proxy de API que estás actualizando, crea un archivo ZIP desde el /apiproxy directorio que contiene los archivos de configuración del 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