Prácticas recomendadas para el diseño y el desarrollo del proxy de API

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

El propósito de este documento es proporcionar un conjunto de estándares y prácticas recomendadas para el desarrollo con Apigee Edge. Entre los temas que se abordan aquí, se incluyen el diseño, la codificación, el uso de políticas, la supervisión y la depuración. La información se recopiló gracias a la experiencia de los desarrolladores que trabajan con Apigee para implementar programas de API exitosos. Este es un documento dinámico y se actualizará periódicamente.

Además de los lineamientos que se indican aquí, también puede resultarte útil la publicación de Comunidad sobre Antipatrones de Apigee Edge.

Estándares de desarrollo

Comentarios y documentación

  • Proporcionar comentarios intercalados en las configuraciones de ProxyEndpoint y TargetEndpoint Los comentarios mejoran la legibilidad de un flujo, en especial cuando los nombres de archivos de políticas no son lo suficientemente descriptivos para expresar la funcionalidad subyacente del flujo.
  • Haz que los comentarios sean útiles. Evita los comentarios evidentes.
  • Usa sangría, espaciado, alineación vertical, etcétera.

Codificación del estilo de framework

La codificación de estilo del marco de trabajo implica almacenar los recursos del proxy de API en tu propio sistema de control de versiones para reutilizarlos en entornos de desarrollo locales. Por ejemplo, para reutilizar una política, almacénala en el control de código fuente, de modo que los desarrolladores puedan sincronizarse con ella y usarla en sus entornos de desarrollo de proxy.

  • Para habilitar DRY (“no te repitas”), siempre que sea posible, las configuraciones de políticas y secuencias de comandos deben implementar funciones especializadas y reutilizables. Por ejemplo, una política exclusiva para extraer parámetros de búsqueda de mensajes de solicitud se podría llamar ExtractVariables.ExtractRequestParameters. Una política dedicada para insertar encabezados de CORS podría llamarse AssignMessage.SetCORSHeaders. Esas políticas podrían almacenarse en tu sistema de control de origen y agregarse a cada proxy de API que necesite extraer parámetros o configurar encabezados de CORS, sin necesidad de crear configuraciones redundantes (y, por lo tanto, menos administrables).
  • Limpia las políticas y los recursos sin usar (JavaScript, Java, XSLT, etc.) de los proxies de API, especialmente los recursos grandes que pueden ralentizar los procedimientos de importación y de implementación.

Convenciones de nombres

  • El atributo name de la política y el nombre de archivo de la política XML deben ser idénticos.
  • El atributo de la política Script and ServicePrompt name y el nombre del archivo de recursos deben ser idénticos.
  • DisplayName debe describir con precisión la función de la política a alguien que nunca haya trabajado con ese proxy de API.
  • Nombra las políticas según su función. Apigee recomienda establecer una convención de nombres coherente para sus políticas. Por ejemplo, usa prefijos cortos seguidos de una secuencia de palabras descriptivas separadas por guiones. Por ejemplo, AM-xxx para las políticas deAssignMessage. Consulta también la herramienta Apigeelint.
  • Usa las extensiones adecuadas para los archivos de recursos, .js para JavaScript, .py para Python y .jar para archivos JAR de Java.
  • Los nombres de las variables deben ser coherentes. Si eliges un estilo, como camelCase o guion bajo, utilízalo en todo el proxy de API.
  • Usa prefijos variables, cuando sea posible, para organizar las variables según su propósito, por ejemplo, Consumer.username y Consumer.password.

Desarrollo del proxy de API

Consideraciones iniciales del diseño

  • Para obtener orientación sobre el diseño de la API de RESTful, descarga el libro electrónico Diseño de la API web: el vínculo faltante.
  • Aprovecha las políticas y la funcionalidad de Apigee Edge siempre que sea posible para compilar proxies de API. Evita codificar toda la lógica de proxy en los recursos de JavaScript, Java o Python.
  • Construye flujos de una manera organizada. Es preferible usar varios flujos, cada uno con una sola condición, en lugar de varios adjuntos condicionales en el mismo flujo previo y posterior.
  • Como "modo a prueba de fallas", crea un proxy de API predeterminado con un ProxyEndpointEndpoint basePath de /. Esto se puede usar para redireccionar las solicitudes a la API base a un sitio de desarrollador, a fin de mostrar una respuesta personalizada o realizar otra acción más útil que mostrar el messaging.adaptors.http.flow.ApplicationNotFound predeterminado.
  • Usa los recursos de TargetServer para separar los parámetros de configuración de TargetEndpoint de URLs concretas, lo cual admite la promoción en todos los entornos.
    Consulta Balanceo de cargas entre servidores de backend.
  • Si tienes varias RouteRules, crea una como predeterminada, es decir, como una RouteRule sin condición. Asegúrate de que la RouteRule predeterminada esté definida al final de la lista de rutas condicionales. Las RouteRules se evalúan de forma vertical en ProxyEndpoint.
    Consulta la referencia de configuración de proxy de la API.
  • Tamaño del paquete de proxy de API: Los paquetes de proxy de API no pueden superar los 15 MB. En Apigee Edge para nube privada, puedes cambiar la limitación de tamaño si modificas la propiedad thrift_framed_transport_size_in_mb en las siguientes ubicaciones: cassandra.yaml (en Cassandra) y conf/apigee/management-server/repository.properties.
  • Control de versiones de API: Para obtener las ideas y recomendaciones de Apigee sobre el control de versiones de API, consulta Control de versiones en el libro electrónico Web API Design: The Missing Link.

Habilita CORS

Antes de publicar tus API, deberás habilitar CORS en tus proxies de API para admitir solicitudes entre dominios del cliente.

CORS (uso compartido de recursos entre dominios) es un mecanismo estándar que permite que las llamadas XMLHttpRequest (XHR) de JavaScript que se ejecutan en una página web interactúen con recursos de dominios que no son de origen. CORS es una solución que se implementa de forma común para la política de mismo origen que aplican todos los navegadores. Por ejemplo, si realizas una llamada XHR a la API de Twitter desde el código JavaScript que se ejecuta en tu navegador, la llamada fallará. Esto se debe a que el dominio que entrega la página a tu navegador no es el mismo que el dominio que entrega la API de Twitter. CORS proporciona una solución a este problema, ya que permite que los servidores se “habiliten” si desean proporcionar uso compartido de recursos entre dominios.

Para obtener información sobre cómo habilitar CORS en los proxies de API antes de publicar las API, consulta Cómo agregar compatibilidad con CORS a un proxy de API.

Tamaño de la carga útil del mensaje

Para evitar problemas de memoria en Edge, el tamaño de la carga útil del mensaje se restringe a 10 MB. Si se exceden esos tamaños, se generará un error protocol.http.TooBigBody.

Este problema también se analiza en esta publicación de la comunidad de Apigee.

A continuación, se incluyen las estrategias recomendadas para manejar tamaños de mensajes grandes en Edge:

  • Solicitudes y respuestas de transmisión. Ten en cuenta que, cuando transmites, las políticas ya no tienen acceso al contenido del mensaje. Consulta Solicitudes y respuestas de transmisión.
  • En Edge para nube privada versión 4.15.07 y anteriores, edita el archivo http.properties del procesador de mensajes para aumentar el límite del parámetro HTTPResponse.body.buffer.limit. Asegúrate de realizar pruebas antes de implementar el cambio en producción.
  • En la versión 4.16.01 y posteriores de Edge para nube privada, las solicitudes con una carga útil deben incluir el encabezado Content-Length o, en caso de transmitir el encabezado “Transfer-Encoding: chunked”. Para realizar un POST dirigido a un proxy de API con una carga útil vacía, debes pasar un valor de Content-Length de 0.
  • En Edge para nube privada versión 4.16.01 y posteriores, configura las siguientes propiedades en /opt/apigee/router.properties o message-processor.properties para cambiar los límites. Para obtener más información, consulta Establece el límite de tamaño del mensaje en el router o el procesador de mensajes.

    Ambas propiedades tienen un valor predeterminado de "10m" que corresponde a 10 MB:
    • conf_http_HTTPRequest.body.buffer.limit
    • conf_http_HTTPResponse.body.buffer.limit

Control de fallas

  • Se pueden usar FaultRules para controlar todas las fallas. (Las políticas RaiseFault se usan para detener el flujo de mensajes y enviar el procesamiento al flujo FaultRules).
  • Dentro del flujo de FaultRules, usa las políticas deAssignMessage para compilar la respuesta ante fallas, no de las políticas de ElevateFault. Ejecuta condicionalmente políticas AssignMessage en función del tipo de falla que ocurra.
  • Siempre incluye un controlador de fallas "catch-all" predeterminado para que las fallas generadas por el sistema se puedan asignar a formatos de respuesta de fallas definidos por el cliente.
  • Si es posible, haz que las respuestas de fallas siempre coincidan con cualquier formato estándar disponible en tu empresa o proyecto.
  • Usa mensajes de error significativos y legibles que sugieran una solución a la condición de error.

Consulta Controla errores.

Para conocer las prácticas recomendadas de la industria, consulta Diseño de respuesta de error de RESTful.

persistencia

Mapas clave-valor

  • Usa mapas de clave-valor solo para conjuntos de datos limitados. No están diseñados para ser un almacén de datos a largo plazo.
  • Ten en cuenta el rendimiento cuando uses mapas de clave-valor, ya que esta información se almacena en la base de datos de Cassandra.

Consulta la política de operaciones de mapas de par clave-valor.

Almacenamiento en caché de respuesta

  • No propagues la caché de respuesta si la respuesta no tiene éxito o si la solicitud no es una GET. Las operaciones de creación, actualización y eliminación no se deben almacenar en caché. <SkipCachePopulation>response.status.code != 200 or request.verb != "GET"</SkipCachePopulation>
  • Propaga la caché con un solo tipo de contenido coherente (por ejemplo, XML o JSON). Después de recuperar una entrada responseCache y, luego, convertirla al tipo de contenido necesario con JSONtoXML o XMLToJSON. Esto evitará almacenar dos, tres o más datos.
  • Asegúrate de que la clave de caché sea suficiente para cumplir con el requisito de almacenamiento en caché. En muchos casos, request.querystring se puede usar como identificador único.
  • No incluyas la clave de API (client_id) en la clave de caché, a menos que se requiera de forma explícita. Por lo general, las API protegidas solo por una clave mostrarán los mismos datos a todos los clientes para una solicitud determinada. No es eficiente almacenar el mismo valor para una cantidad de entradas basadas en la clave de API.
  • Establece intervalos de vencimiento de caché adecuados para evitar lecturas no confirmadas.
  • Siempre que sea posible, intenta que la política de caché de respuesta que propaga la caché se ejecute en el flujo de respuesta ProxyEndpoint lo más tarde posible. En otras palabras, haz que se ejecute después de los pasos de traducción y mediación, incluida la encriptación basada en JavaScript y la conversión entre JSON y XML. Si almacenas en caché los datos mediados, evitarás el costo de rendimiento que implica ejecutar el paso de mediación cada vez que recuperas datos almacenados en caché.

    Ten en cuenta que tal vez quieras almacenar en caché datos sin mediación si la mediación da como resultado una respuesta diferente de una solicitud a otra.

  • La política de caché de respuesta para buscar la entrada de caché debe ocurrir en la solicitud PreFlow de ProxyEndpoint. Evita implementar demasiada lógica, distinta de la generación de claves de caché, antes de mostrar una entrada de caché. De lo contrario, se minimizan los beneficios del almacenamiento en caché.
  • En general, debes mantener siempre la búsqueda de caché de respuesta lo más cerca posible de la solicitud del cliente. Por el contrario, debes conservar la población de caché de respuesta lo más cerca posible de la respuesta del cliente.
  • Cuando uses varias políticas de caché de respuesta diferentes en un proxy, sigue estos lineamientos a fin de garantizar un comportamiento discreto para cada uno:
    • Ejecuta cada política en función de condiciones mutuamente excluyentes. Esto ayudará a garantizar que se ejecute solo una de las múltiples políticas de caché de respuesta.
    • Define diferentes recursos de caché para cada política de caché de respuesta. Debes especificar el recurso de caché en el elemento <CacheResource> de la política.

Consulta Política de caché de respuesta.

Política y código personalizado

¿Deseas un código personalizado o una política?

  • Usa las políticas integradas en primer lugar (siempre que sea posible). Las políticas de Apigee se endurecen, optimizan y admiten. Por ejemplo, usa las políticas estándar deAssignMessage y ExtractVariables en lugar de JavaScript (cuando sea posible) para crear cargas útiles, extraer información de cargas útiles (XPath, JSONPath), etcétera.
  • Se prefiere JavaScript en lugar de Python y Java. Sin embargo, si el rendimiento es el requisito principal, Java debe usarse en JavaScript.

JavaScript

  • Usa JavaScript si es más intuitivo que las políticas de Apigee (por ejemplo, cuando configuras target.url para muchas combinaciones de URI diferentes).
  • Análisis de carga útil complejo, como la iteración a través de un objeto JSON y la codificación o decodificación en Base64
  • La política de JavaScript tiene un límite de tiempo, por lo que se bloquean los bucles infinitos.
  • Usa siempre los pasos de JavaScript y coloca los archivos en la carpeta de recursos jsc. El tipo de política de JavaScript compila previamente el código en el momento de la implementación.

Consulta Proxies de API de programación con JavaScript.

Java

  • Usa Java si el rendimiento es la prioridad más alta o si la lógica no se puede implementar en JavaScript.
  • Incluye archivos fuente de Java en el seguimiento del código fuente.

Consulta Convierte la respuesta en mayúsculas con un texto destacado de Java y la política de texto destacado de Java para obtener información sobre el uso de Java en proxies de API.

Python

  • No uses Python, a menos que sea absolutamente obligatorio. Las secuencias de comandos de Python pueden generar cuellos de botella de rendimiento para ejecuciones simples, ya que se interpretan en el entorno de ejecución.

Texto destacado en secuencias de comandos (Java, JavaScript, Python)

  • Usa un try-catch global o equivalente.
  • Genera excepciones significativas y capturalas correctamente para usarlas en respuestas a fallas.
  • Genera y detecta las excepciones con anticipación. No uses el try/catch global para manejar todas las excepciones.
  • Realiza verificaciones nulas y no definidas cuando sea necesario. Un ejemplo de cuándo hacer esto es cuando se recuperan variables de flujo opcionales.
  • Evita realizar solicitudes HTTP/S dentro de un texto destacado de la secuencia de comandos. En su lugar, usa la política ServiceReferencia de Apigee, ya que la política controla las conexiones con facilidad.

JavaScript

  • JavaScript en la plataforma de API admite XML mediante E4X.

Consulta el modelo de objetos de JavaScript.

Java

  • Cuando accedas a cargas útiles de mensajes, intenta usar context.getMessage() en lugar de context.getResponseMessage o context.getRequestMessage. Esto garantiza que el código pueda recuperar la carga útil, tanto en el flujo de solicitud como en el de respuesta.
  • Importa bibliotecas a la organización o entorno de Apigee Edge y no las incluyas en el archivo JAR. Esto reduce el tamaño del paquete y permitirá que otros archivos JAR accedan al mismo repositorio de bibliotecas.
  • Importa archivos JAR mediante la API de recursos de Apigee en lugar de incluirlos en la carpeta de recursos del proxy de la API. Esto reducirá los tiempos de implementación y permitirá que varios proxies de API hagan referencia a los mismos archivos JAR. Otro beneficio es el aislamiento del cargador de clase.
  • No uses Java para manejar recursos (por ejemplo, crear y administrar grupos de subprocesos).

Consulta Convierte la respuesta en mayúsculas con un texto destacado de Java.

Python

  • Genera excepciones significativas y detecta estas excepciones para su uso en las respuestas de fallas de Apigee.

Consulta la política de Python Script.

ServiceCallouts

  • Hay muchos casos prácticos válidos para el uso del encadenamiento de proxy, en los que se usa un texto destacado de servicio en un proxy de API para llamar a otro proxy de API. Si usas el encadenamiento de proxy, asegúrate de evitar las leyendas recursivas de “bucle infinito” en el mismo proxy de API.

    Si te conectas entre proxies que se encuentran en la misma organización y el mismo entorno, asegúrate de consultar Cómo encadenar proxies de API para obtener más información sobre la implementación de una conexión local que evita sobrecargas de red innecesarias.

  • Crea un mensaje de solicitud de ServiceFeatured con la política deAssignMessage y propaga el objeto de solicitud en una variable de mensaje. (Esto incluye configurar la carga útil, la ruta de acceso y el método de la solicitud).
  • La URL que se configura dentro de la política requiere la especificación de protocolo, lo que significa que la parte del protocolo de la URL (por ejemplo, https://) no se puede especificar mediante una variable. Además, debes usar variables independientes para la parte del dominio de la URL y el resto de la URL. Por ejemplo: https://{domain}/{path}.
  • Almacena el objeto de respuesta para un ServiceCallout en una variable de mensaje separada. Luego, puedes analizar la variable del mensaje y mantener intacta la carga útil del mensaje original para que la usen otras políticas.

Consulta Política de texto destacado del servicio.

Accede a entidades

Política AccessEntity

  • Para mejorar el rendimiento, busca apps por uuid en lugar del nombre de la app.

Consulta la política de Entidad de acceso.

Logging

  • Usa una política syslog común en conjuntos y dentro del mismo paquete. Esto mantendrá un formato de registro coherente.

Consulta la política MessageLogging.

Supervisión

No es necesario que los clientes de Cloud verifiquen los componentes individuales de Apigee Edge (routers, procesadores de mensajes, etcétera). El equipo de operaciones globales de Apigee supervisa a fondo todos los componentes, junto con las verificaciones de estado de las API, según las solicitudes del cliente.

Estadísticas de Apigee

Las estadísticas puede proporcionar supervisión de API no críticas a medida que se miden los porcentajes de error.

Consulta los paneles de Analytics.

Trace

La herramienta de seguimiento de la IU de administración perimetral de API es útil para depurar problemas de API en tiempo de ejecución, durante las operaciones de desarrollo o producción de una API.

Consulta Usa la herramienta seguimiento.

Seguridad