Estás viendo la documentación de Apigee Edge.
Ve a la
Documentación de Apigee X. información
Publica las API en tu portal a fin de que estén disponibles para su consumo por parte de los desarrolladores de apps, como se describe en las siguientes secciones.
Descripción general de la publicación de API
El proceso de publicación de API en tu portal es un proceso de dos pasos:
- Selecciona el producto de API que deseas publicar en tu portal.
- Escribe documentación de referencia de las API a partir de una instantánea de tu documento de OpenAPI o del esquema de GraphQL para que los desarrolladores de apps puedan aprender sobre las API. (Para obtener más información sobre las instantáneas, consulta ¿Qué es una instantánea?)
¿Qué se publica en el portal?
Cuando publicas una API, las siguientes actualizaciones se realizan en tu portal automáticamente:La página de la API (que se incluye en el portal de muestra) proporciona una lista de todas las API publicadas en tu portal, en orden alfabético con vínculos a la documentación de referencia de la API correspondiente a fin de obtener más información. De manera opcional, puedes personalizar lo siguiente:
- Imagen que se muestra para cada tarjeta de la API
- Categorías usadas para etiquetar API que permiten a los desarrolladores descubrir API relacionadas en la página de las API
SmartDocs (OpenAPI)
Cuando publicas una API con un documento de OpenAPI, la documentación de referencia de la API de SmartDocs se agrega a tu portal.
Los desarrolladores pueden revisar la documentación de referencia de la API de SmartDocs y usar el panel Probar esta API para realizar una solicitud a la API y ver el resultado. Prueba esta API con extremos no seguros o extremos seguros con Basic, clave de API, o autenticación de OAuth, según el método de seguridad definido en tu documento de OpenAPI. Para OAuth, se admiten los siguientes flujos: código de autorización, contraseña y credenciales del cliente.
Haz clic en para expandir el panel Probar esta API. El panel expandido te permite ver los ejemplos de llamada y código curl en varios formatos, como HTTP, Python, Node.js y muchos más, como se muestra a continuación.
GraphQL Explorer
Cuando publicas una API con un esquema de GraphQL, se agrega GraphQL Explorer a tu portal. GraphQL Explorer es una zona de pruebas interactiva para ejecutar consultas en la API. El explorador se basa en GraphiQL, una implementación de referencia del IDE de GraphQL que desarrolló GraphQL Foundation.
Los desarrolladores pueden usar GraphQL Explorer para explorar la documentación interactiva basada en esquemas, compilar y ejecutar consultas, ver los resultados de las consultas y descargar el esquema. Para asegurar el acceso a tu API, los desarrolladores pueden pasar los encabezados de autorización en el panel Encabezados de solicitud.
Para obtener más información sobre GraphQL, consulta graphql.org.
¿Qué es una instantánea?
Cada documento de OpenAPI o GraphQL funciona como la fuente de información durante todo el ciclo de vida de una API. Se usa el mismo documento en cada fase del ciclo de vida de la API, desde el desarrollo hasta la publicación y la supervisión. Cuando modificas un documento, debes conocer el efecto que los cambios tienen en tu API a través de otras fases del ciclo de vida, como se describe en ¿Qué sucede si modificas un documento?
Cuando publicas tu API, tomas una instantánea del documento de OpenAPI o GraphQL para procesar la documentación de referencia de la API. Esa instantánea representa una versión particular del documento. Si modificas el documento, puedes decidir tomar otra instantánea para reflejar los cambios más recientes en la documentación de referencia de la API.
Acerca de las URL de devolución de llamada
Si tus apps requieren una URL de devolución de llamada, como la que se usa cuando se utiliza el tipo de autorización de código de autorización OAuth 2.0 (que a menudo se denomina "OAuth de tres segmentos"), puedes requerir que los desarrolladores especifiquen una URL de devolución de llamada cuando registren sus aplicaciones. La URL de devolución de llamada generalmente especifica la URL de una aplicación designada para recibir un código de autorización en nombre de la app cliente. Para obtener más información, consulta la sección sobre cómo implementar el tipo de otorgamiento de código de autorización.
Puedes configurar si necesitas o no una URL de devolución de llamada durante el registro de la app cuando se agrega una API a tu portal. Puedes modificar este parámetro de configuración en cualquier momento, tal como se describe en Administra la URL de devolución de llamada para una API.
Cuando se registra una app, los desarrolladores deben ingresar una URL de devolución de llamada para todas las APIs que la requieren, como se describe en la sección sobre cómo registrar apps.
Configura tu proxy de API para que admita "Probar esta API"
Antes de publicar tus API con un documento de OpenAPI, deberás configurar tu proxy de API para admitir solicitudes en el panel Probar esta API en la documentación de referencia de la API de SmartDocs, de la siguiente manera:
- Agregar compatibilidad con CORS a los proxies de tu API para aplicar las solicitudes de origen cruzado del cliente
CORS es un mecanismo estándar que permite que las llamadas JavaScript XMLHttpRequest (XHR) que se ejecutan en una página web interactúen con recursos de dominios ajenos a origen. CORS es una solución implementada con frecuencia en la "política del mismo origen" que aplican todos los navegadores.
- Actualiza la configuración de tu proxy de API si usas la autenticación básica o la OAuth2
En la siguiente tabla, se resumen los requisitos de configuración del proxy de API para admitir el panel Prueba esta API en la documentación de referencia de la API de SmartDocs de acuerdo con el acceso de autenticación.
Acceso a la autenticación | Requisitos de configuración de la política |
---|---|
Ninguna o clave de API | Agrega compatibilidad con CORS al proxy de tu API Para mayor comodidad, usa la solución de ejemplo de CORS que se proporciona en GitHub o sigue los pasos descritos en la sección sobre cómo agregar asistencia de CORS a un proxy de API. |
Autenticación básica | Sigue los siguientes pasos:
|
OAuth2 |
|
Explora el catálogo de APIs
Para ver el catálogo de APIs, haz lo siguiente: 1. Selecciona Publicar > Portales y selecciona tu portal. 2. Haz clic en Catálogo de APIs en la página principal del portal. También puedes seleccionar Catálogo de APIs en el menú desplegable del portal en la barra de navegación superior.
La pestaña API del catálogo de API muestra una lista de las API que se agregaron a tu portal.
Como se destacó en la figura anterior, la pestaña de API te permite hacer lo siguiente:
- Ver los detalles de las API disponibles en tu portal
- Agregar una API a tu portal
- Editar una API en tu portal mediante una o más de las siguientes tareas:
- Administra la instantánea de un documento asociado con un producto de API para actualizar la documentación de referencia de la API.
- Cómo publicar una API o anular su publicación en tu portal
- Administrar la visibilidad de una API en tu portal:
- Administrar la URL de devolución de llamada para una API
- Administrar la imagen de una tarjeta de API
- Etiquetar una API a través de categorías
- Editar el título y la descripción de la API
- Quitar una API de tu portal
- Administrar las categorías usadas para descubrir API relacionadas
- Identifica rápidamente las especificaciones que están desactualizadas o que se borraron de la tienda de especificaciones
- Identificar rápidamente las APIs “huérfanas” cuyos productos de API asociados se quitaron de Edge y volver a crear el producto de API o borrar la API de tu portal
Agrega una API a tu portal
Para agregar una API a tu portal, sigue estos pasos:
- Accede al catálogo de API.
- Haz clic en la pestaña API si no está seleccionada.
Haz clic en +.
Se muestra el cuadro de diálogo Agregar producto de API al catálogo.
Selecciona el producto de API que quieres agregar a tu portal.
Haz clic en Siguiente. Aparecerá la página de detalles de la API.
Configura el contenido de la documentación de referencia de la API y su visibilidad en el portal:
Campo Descripción Publicada Selecciona Published para publicar la API en tu portal. Si no estás listo para publicar la API, anula la selección de la casilla de verificación. Puedes cambiar la configuración más adelante, como se describe en Publica o anula la publicación de una API en tu portal. Título para mostrar Actualiza el título de la API que se muestra en el catálogo. De forma predeterminada, se usa el nombre del producto de API. Puedes cambiar el título de la pantalla más adelante, como se describe en Edita el título y la descripción de la pantalla. Descripción para mostrar Actualiza la descripción de la API que se muestra en el catálogo. De forma predeterminada, se usa la descripción del producto de la API. Puedes cambiar la descripción de la pantalla más adelante, como se describe en Edita el título y la descripción de la pantalla. Requerir que los desarrolladores especifiquen una URL de devolución de llamada Habilita esta opción si deseas exigir que los desarrolladores de aplicaciones especifiquen una URL de devolución de llamada. Puedes agregar o actualizar la URL de devolución de llamada más tarde, como se describe en Administra la URL de devolución de llamada para una API. Documentación de la API Para usar un documento de OpenAPI, sigue estos pasos: - Selecciona Documento de OpenAPI.
- Haz clic en Seleccionar documento.
- Realiza uno de los siguientes pasos:
- Haz clic en la pestaña Mis especificaciones y selecciona una especificación de la tienda de especificaciones.
- Haz clic en la pestaña Subir archivo y sube un archivo.
- Haz clic en la pestaña Importar desde una URL y, luego, importa una especificación desde una URL.
- Haz clic en Seleccionar.
Para usar un esquema de GraphQL, haz lo siguiente:
- Selecciona Esquema de GraphQL.
- Haz clic en Seleccionar documento.
- Navega hasta el esquema de GraphQL y selecciónalo.
- Haz clic en Seleccionar.
Como alternativa, puedes seleccionar Sin documentación y agregar una más tarde, después de agregar la API, como se describe en Administra la instantánea del documento.
Visibilidad de la API Si no te inscribiste en la versión beta de la función de administración de públicos, selecciona una de las siguientes opciones:
- Usuarios anónimos para permitir que todos los usuarios vean la página
- Usuarios registrados para permitir que solo los usuarios registrados vean la página
Si te inscribiste en la versión beta de la función de administración de públicos, selecciona una de las siguientes opciones:
- Pública (visible para todos) para que todos los usuarios vean la API.
- Usuarios autenticados para permitir que solo los usuarios registrados vean la API.
- Públicos seleccionados para seleccionar los públicos específicos que desea que puedan ver la API.
Puedes administrar la visibilidad del público más adelante, como se describe en la sección sobre cómo administrar la visibilidad de una API en tu portal.
Imagen visible Para mostrar una imagen en la tarjeta de la API en la página de API, haz clic en Seleccionar imagen. En el diálogo Seleccionar imagen, seleccione una imagen existente, suba una imagen nueva o proporcione la URL de una imagen externa y haga clic en Seleccionar. Obtenga una vista previa de la miniatura de la API y haga clic en Seleccionar. Puedes agregar una imagen más tarde, como se describe en Administra la imagen para una tarjeta de API. Si especificas una imagen con una URL externa, esta no se subirá a tus recursos. Además, la carga de la imagen en el portal integrado estará sujeta a su disponibilidad, que puede estar bloqueada o restringida por las políticas de seguridad del contenido. Categorías Agrega las categorías en las que se etiquetará la API para permitir que los desarrolladores de aplicaciones descubran las API relacionadas en la página de API. Para identificar una categoría, haz lo siguiente:
- Selecciona una categoría de la lista desplegable.
- Escribe su nombre y presiona Intro para agregar una categoría nueva. La nueva categoría se agregará a la página Categorías y estará disponible cuando se agreguen o editen otras API.
Haz clic en Guardar.
Administra la instantánea del documento
Después de publicar la API, puedes obtener una nueva instantánea del documento de OpenAPI o GraphQL en cualquier momento para actualizar la documentación de referencia de la API publicada en tu portal.
Para administrar la instantánea del documento, sigue estos pasos:
- Accede al catálogo de API.
- Haz clic en la pestaña APIs si no está seleccionada.
- Haz clic en la fila de la API que quieres editar.
- Verifica el estado de la instantánea. Si está desactualizado, se muestra el siguiente mensaje:
- Haga clic en .
- Realiza una de las siguientes tareas:
- Para actualizar una instantánea de un documento de OpenAPI que está desactualizado, haz clic en Actualizar instantánea.
- Si deseas cambiar el documento que se usa para generar la documentación de la API, en Documentación de la API, haz clic en Seleccionar documento y selecciona el documento nuevo.
- Haz clic en Guardar.
La documentación de referencia de la API se renderiza desde el documento y se agrega a la página Referencia de la API. El estado de la instantánea se actualiza a la versión actual:
Publica o anula la publicación de una API en tu portal
Publica o anula la publicación de una API en tu portal
- Accede al catálogo de API.
- Haz clic en la pestaña APIs si no está seleccionada.
- Haz clic en la fila de la API que quieres editar.
- Haga clic en .
- En detalles de la API, selecciona o anula la selección de Publicada (incluida en el catálogo) para publicar o anular la publicación de la API en tu portal, respectivamente.
- Haz clic en Guardar.
Administra la visibilidad de una API en tu portal:
Para administrar la visibilidad de una API en tu portal, debes permitir el acceso a lo siguiente:
- Pública (visible para todos)
- Usuarios autenticados
- Públicos seleccionados (si se inscribió en la versión beta de la función de administración de públicos)
Para administrar la visibilidad de una API en tu portal, haz lo siguiente:
- Accede al catálogo de API.
- Haz clic en la pestaña APIs si no está seleccionada.
- Haz clic en la fila de la API que quieres editar.
- Haga clic en .
- En la visibilidad de la API, selecciona una de las siguientes opciones:
Selecciona la configuración de visibilidad. Si te inscribiste en la versión beta de la función de públicos, selecciona una de las siguientes opciones:
- Pública (visible para todos) para que todos los usuarios vean la página.
- Usuarios Autenticados para que solo los usuarios registrados vean la página.
- Públicos seleccionados para seleccionar públicos específicos que tu deseas que vean la página. Consulta la sección sobre cómo administrar los públicos de tu portal.
- Usuarios anónimos para que todos los usuarios vean la página.
- Usuarios registrados para que solo los usuarios registrados vean la página.
Haz clic en Enviar.
Administra la URL de devolución de llamada para una API
Administra la URL de devolución de llamada para una API, consulta Acerca de las URL de devolución de llamada.
Administra la URL de devolución de llamada para una API
- Accede al catálogo de API.
- Haz clic en la pestaña APIs si no está seleccionada.
- Haz clic en la fila de la API que quieres editar.
- Haga clic en .
- En detalles de la API, selecciona o anula la selección de Publicada (incluida en el catálogo) para publicar o anular la publicación de la API en tu portal, respectivamente.
- Haz clic en Guardar.
Administrar la imagen de una tarjeta de API
Para administrar la imagen que aparece con una tarjeta de API en la página de API, agrega o cambia la imagen actual.
Para administrar la imagen de una tarjeta de API, haz lo siguiente:
- Accede al catálogo de API.
- Haz clic en la pestaña APIs si no está seleccionada.
- Haz clic en la fila de la API que quieres editar.
- Haga clic en .
En los detalles de API, haz lo siguiente:
- Haz clic en Seleccionar imagen para especificar o subir una imagen si no hay ninguna imagen seleccionada.
- Haz clic en Cambiar imagen para especificar o subir otra imagen.
- Haz clic en x en la imagen para quitarla.
Cuando especifiques una imagen, especifica una imagen con una URL externa usada para el elemento de catálogo o una ruta de acceso de archivo para archivos de imagen almacenados en el portal, por ejemplo,
/files/book-tree.jpg
. Si especificas la URL de una imagen externa, esta no se subirá a tus elementos. Además, la carga de la imagen en el portal integrado estará sujeta a su disponibilidad, que puede estar bloqueada o restringida por las políticas de seguridad del contenido.Haz clic en Guardar.
Etiquetar una API a través de categorías
Etiqueta una API mediante categorías de una de las siguientes maneras:
- Administra las categorías a las que se etiqueta una API cuando la editas, como se describe a continuación.
- Administra las API etiquetadas a una categoría cuando editas la categoría.
Para etiquetar una API a las categorías cuando editas la API, sigue estos pasos:
- Accede al catálogo de API.
- Haz clic en la pestaña APIs si no está seleccionada.
- Haz clic en la fila de la API que quieres editar.
- Haga clic en .
- Haz clic en el campo Categorías y realiza uno de los siguientes pasos:
- Selecciona una categoría de la lista desplegable.
- Escribe su nombre y presiona Intro para agregar una categoría nueva. La nueva categoría se agregará a la página Categorías y estará disponible cuando se agreguen o editen otras API.
- Repite para etiquetar la API a más categorías.
- Haz clic en Guardar.
Edita el título y la descripción visibles
Para editar el título y la descripción de la pantalla, sigue estos pasos:
- Accede al catálogo de API.
- Haz clic en la pestaña APIs si no está seleccionada.
- Haz clic en la fila de la API que quieres editar.
- Haga clic en .
- Edita los campos Título para mostrar y Descripción para mostrar, según sea necesario.
- Haz clic en Guardar.
Quita una API de tu portal
Para quitar una API de tu portal, sigue estos pasos:
- Accede al catálogo de API.
- Selecciona las API si aún no lo están.
- Coloca el cursor sobre la API de la lista para ver el menú de acciones.
- Haz clic en .
Administra las categorías usadas para descubrir APIs relacionadas
Etiqueta una API mediante categorías para permitir que los desarrolladores de aplicaciones descubran API relacionadas en la página de API del portal en vivo. Agrega y administra categorías, como se describe en las siguientes secciones.
Explora la página Categorías
Para ver la página Categorías, haz lo siguiente:
- Selecciona Publicar > Portales y selecciona tu portal.
- Haz clic en Catálogo de API en la página principal del portal.
También puedes seleccionar Catálogo de API en el menú desplegable del portal en la barra de navegación superior.
- Haga clic en la pestaña Categorías.
La pestaña Categorías en el catálogo de API muestra la lista de las categorías que se definieron para tu portal.
Como se destaca en la figura anterior, la página de APIs te permite hacer lo siguiente:
- Visualiza las categorías y las API a las que se etiquetan
- Agregar una categoría
- Editar una categoría
- Borrar una categoría
- Administrar las API publicadas en tu portal. Consulta Explora el catálogo de APIs.
Agregar una categoría
Agrega una categoría de una de las siguientes maneras:
- Ingresa el nombre de una categoría cuando agregues una API al portal.
- Agrega una categoría manualmente como se describe a continuación
La nueva categoría se agregará a la página Categorías y estará disponible cuando se agreguen o editen otras API.
Para agregar una categoría de forma manual, haz lo siguiente:
- Accede a la página Categorías.
- Haz clic en +.
- Ingresa el nombre de la nueva categoría.
- De manera opcional, selecciona una o más API que quieras etiquetar a la categoría.
- Haz clic en Crear.
Editar una categoría
Para editar una categoría, sigue estos pasos:
- Accede a la página Categorías.
- Haga clic en .
- Edita el nombre de la categoría.
- Agrega o quita etiquetas de API
- Haz clic en Guardar.
Borrar una categoría
Cuando borras una categoría, también se borran todas las etiquetas de la API.
Para borrar una categoría, haz lo siguiente:
- Accede a la página Categorías.
- Coloca el cursor sobre la categoría que quieras editar para que se muestre el menú de acciones.
- Haz clic en .
- Edita el nombre de la categoría.
- Agrega o quita API
- Haz clic en Guardar.
Soluciona problemas con tus APIs publicadas
En las siguientes secciones, se proporciona información para ayudarte a solucionar errores específicos con nuestras API publicadas.
Error: No se pudo recuperar el error que se mostró cuando se usó la API
Cuando uses esta API, si se muestra el error TypeError: Failed to fetch
, ten en cuenta las siguientes causas y resoluciones posibles:
En el caso de los errores de contenido mixto, el error puede deberse a un problema conocido de una IU de Swagger. Una posible solución es asegurarte de especificar HTTPS antes de HTTP en la definición
schemes
en tu documento de OpenAPI. Por ejemplo:schemes: - https - http
En el caso de los errores de restricción de uso compartido de recursos entre dominios (CORS), asegúrate de que el CORS sea compatible con los proxies de API. CORS es un mecanismo estándar que habilita las solicitudes de orígenes cruzados del cliente. Consulta Configura tu proxy de API para que admita esta API.
Error: El encabezado “Access-Control-Allow-Origin” contiene múltiples valores “*, *”, pero solo se permite uno.
Cuando uses esta API, es posible que recibas el siguiente mensaje de error si el encabezado Access-Control-Allow-Origin
ya existe:
The 'Access-Control-Allow-Origin' header contains multiple values '*, *', but only one is allowed.
Si deseas de corregir este error, modifica la política de AssignMessage para que use <Set>
a fin de establecer los encabezados de CORS en lugar de <Add>
, como se muestra en el siguiente extracto.
Para obtener más información, consulta el artículo de la comunidad correspondiente.
<AssignMessage async="false" continueOnError="false" enabled="true" name="add-cors"> <DisplayName>Add CORS</DisplayName> <FaultRules/> <Properties/> <Set> <Headers> <Header name="Access-Control-Allow-Origin">{request.header.origin}</Header> <Header name="Access-Control-Allow-Headers">origin, x-requested-with, accept, content-type, authorization</Header> <Header name="Access-Control-Max-Age">3628800</Header> <Header name="Access-Control-Allow-Methods">GET, PUT, POST, DELETE</Header> </Headers> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="response"/> </AssignMessage>
Error: No se permite el campo del encabezado de la solicitud
Cuando se usa Probar esta API, si recibes un error Request header field not allowed
, similar al ejemplo que se muestra a continuación, es posible que debas actualizar los encabezados compatibles con la política de CORS. Por ejemplo:
Access to XMLHttpRequest ... has been blocked by CORS policy: Request header field
content-type is not allowed by Access-Control-Allow-Headers in preflight response
En este ejemplo, debes agregar el encabezado content-type
a la sección Access-Control-Allow-Headers
en tu política de CORS MessageMessage, como se describe en Adjunta una política de CORS a un nuevo proxy de API.
Error: Se denegó el acceso cuando se realizó una llamada a un proxy de API mediante OAuth2
La política OAuthV2 de Apigee muestra una respuesta de token que contiene ciertas propiedades que no cumplen con RFC. Por ejemplo, la política mostrará un token con el valor BearerToken
, en lugar del valor esperado compatible con RFC Bearer
. Esta respuesta token_type
no válida puede dar como resultado un error Access denied
cuando se usa esta API de prueba.
Para corregir este problema, puede crear una política de JavaScript o de AssignMessage para transformar el resultado de la política en un formato que cumpla con los requisitos. Para obtener más información, consulta Comportamiento no compatible con RFC.