Publica tus APIs (versión original)

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

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:

  1. Selecciona el producto de API que deseas publicar en tu portal.
  2. Genera automáticamente documentación de referencia de la API a partir de una instantánea de tu especificación de OpenAPI para que los desarrolladores de apps puedan aprender sobre tus APIs. (Para obtener más información sobre las instantáneas, consulta ¿Qué es una instantánea de una Especificación de OpenAPI?

Cuando publicas una API en tu portal, las siguientes actualizaciones se realizan automáticamente:

  • Se agrega una página de referencia de la API a tu portal
    La página de referencia de la API muestra la documentación de referencia de la API que generas automáticamente a partir de una instantánea de tu especificación de OpenAPI. Los desarrolladores pueden revisar la documentación de tu API y hacer clic en Probar para realizar una solicitud a la API y ver el resultado.

    Nota: No puedes editar el contenido de esta página directamente. No aparece en la lista de páginas del portal.

  • Se agrega un vínculo a la página de referencia de la API.
    La página de las APIs (incluida en el portal de muestra) proporciona una lista de todas las APIs publicadas en tu portal con vínculos a la documentación de referencia de la API correspondiente para obtener más información.

    Nota: No puedes editar el contenido de esta página directamente. No aparece en la lista de páginas del portal.

¿Qué es una instantánea de una Especificación de OpenAPI?

Cada Especificación de OpenAPI sirve como fuente de información a lo largo del ciclo de vida de una API. Se usa la misma especificación en cada fase del ciclo de vida de la API, desde el desarrollo hasta la publicación y la supervisión. Cuando modificas una especificación, 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 una especificación?

Cuando publicas tu API, tomas una instantánea de la especificación de OpenAPI para generar documentación de referencia de la API. Esa instantánea representa una versión particular de la especificación en el almacén de especificaciones. Si modificas la especificación de OpenAPI con el editor de especificaciones, puedes decidir tomar otra instantánea de la especificación para reflejar los cambios más recientes en la documentación de referencia de la API.

Agrega compatibilidad con CORS a tus proxies de API

Antes de publicar tus APIs, deberás agregar compatibilidad con CORS a tus proxies de API para admitir solicitudes de origen cruzado del cliente.

CORS (uso compartido de recursos de origen cruzado) 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 implementada con frecuencia en la política del 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 el 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 "habiliten" si desean proporcionar uso compartido de recursos de origen cruzado.

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

Nota: La mayoría de los navegadores modernos aplican CORS. Consulta la lista completa de navegadores compatibles. Para obtener una descripción detallada de CORS, consulta la Recomendación de W3C de uso compartido de recursos entre dominios.

Explora la página de las APIs

Para acceder a la página de APIs, haz lo siguiente:

  1. Selecciona Publicar > Portales y selecciona tu portal.
  2. Haz clic en APIs en la página principal del portal.

También puedes seleccionar APIs en el menú desplegable del portal en la barra de navegación superior.

Se muestra la lista de APIs.

Referencia de la API

Como se destacó en la figura anterior, la página de APIs te permite hacer lo siguiente:

Agrega una API a tu portal

Nota: Puedes agregar un máximo de 100 APIs a tu portal.

Para agregar una API a tu portal, sigue estos pasos:

  1. Selecciona Publicar > Portales y selecciona tu portal.
  2. Haz clic en APIs en la página principal del portal.
    También puedes seleccionar APIs en el menú desplegable del portal en la barra de navegación superior.
  3. Haz clic en + API.
    Se muestra el diálogo Add API Product to Portal.

  4. En la pestaña API Product del diálogo, selecciona el producto de API que deseas agregar a tu portal.

  5. Haz clic en Siguiente.

  6. Selecciona el origen que usar para la instantánea.
    Si creaste el proxy de API incluido en el producto de API con una especificación de OpenAPI, selecciona la especificación en la lista desplegable.
    Agregar instantánea

    Como alternativa, puedes seleccionar una de las siguientes opciones:

  7. Selecciona la casilla de verificación Publicado para publicar la API en tu portal. Anula la selección de Publicado si no estás listo para publicar la API.
    Puedes cambiar el parámetro de configuración más adelante, como se describe en Publica o anula la publicación de una API en tu portal.

  8. En Público, selecciona una de las siguientes opciones para administrar el público de tu API permitiendo el acceso a lo siguiente:

    • Usuarios anónimos para que todos los usuarios vean la página.
    • Usuarios registrados para que solo los usuarios registrados vean la página.

    Puedes cambiar el parámetro de configuración más adelante, como se describe en Administra el público de una API en tu portal.

  9. Haz clic en Finalizar.

Toma una instantánea de la especificación

Después de publicar la API, puedes obtener una nueva instantánea de la especificación de OpenAPI en cualquier momento para actualizar la documentación de referencia de la API publicada en tu portal.

Para tomar una instantánea de la especificación de OpenAPI, haz lo siguiente:

  1. Selecciona Publicar > Portales y selecciona tu portal.
  2. Haz clic en APIs en la página principal del portal.
    También puedes seleccionar APIs en el menú desplegable del portal en la barra de navegación superior.
  3. Coloca el cursor sobre la API de la que quieres tomar una instantánea para que se muestren las acciones.

  4. Haga clic en Ícono de instantánea.

    Nota: Se mostrará un mensaje si tu instantánea está actualizada con la especificación de la fuente seleccionada.

  5. Selecciona una especificación existente en el menú desplegable Fuente de instantánea o selecciona Elegir otra especificación para seleccionar o subir una especificación nueva que se usará para generar la documentación de la API. Como alternativa, puedes seleccionar Sin especificación para quitar la especificación actual.

  6. Haz clic en Actualizar instantánea (o Quitar instantánea, si seleccionaste Sin especificaciones).

La documentación de referencia de la API se genera a partir de la especificación y se agrega a la página Referencia de la API.

Publica o anula la publicación de una API en tu portal

Publica o anula la publicación de una API en tu portal

  1. Selecciona Publicar > Portales y selecciona tu portal.
  2. Haz clic en APIs en la página principal del portal.
    También puedes seleccionar APIs en el menú desplegable del portal en la barra de navegación superior.
  3. Coloca el cursor sobre la API que deseas publicar o anular la publicación.
  4. Haga clic en Ícono de configuración.
  5. Selecciona la casilla de verificación Habilitado para publicar la API en tu portal. Anula la selección de Habilitado para anular la publicación de la API.
  6. Haz clic en Guardar.

Administra el público de una API en tu portal

Administra el público de tu API en el portal permitiendo el acceso a lo siguiente:

  • Todos los usuarios
  • Solo los usuarios registrados

Para administrar el público de una API en tu portal, haz lo siguiente:

  1. Selecciona Publicar > Portales y selecciona tu portal.
  2. Haz clic en APIs en la página principal del portal.
    También puedes seleccionar APIs en el menú desplegable del portal en la barra de navegación superior.
  3. Coloca el cursor sobre la API para la que deseas administrar el público y mostrar las acciones.
  4. Haz clic en Ícono de configuración.
  5. En Público, selecciona una de las siguientes opciones:
    • Usuarios anónimos para permitir que todos los usuarios vean el producto de API
    • Usuarios registrados para permitir que solo los usuarios registrados vean el producto de la API
  6. Haz clic en Guardar.

Quita una API de tu portal

Para quitar una API de tu portal, sigue estos pasos:

  1. Selecciona Publicar > Portales y selecciona tu portal.
  2. Haz clic en APIs en la página principal del portal.
    También puedes seleccionar APIs en el menú desplegable del portal en la barra de navegación superior.
  3. Coloca el cursor sobre la API de la lista para ver el menú de acciones.
  4. Haz clic en Borrar.

Soluciona problemas con tus APIs publicadas

Cuando uses Probar, si se devuelve 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 la especificación de OpenAPI. Por ejemplo: 

     schemes:
   - https
   - http

  • En el caso de los errores de restricción de CORS (uso compartido de recursos de origen cruzado), asegúrate de que tus proxies de API admitan CORS. CORS es un mecanismo estándar que habilita las solicitudes de orígenes cruzados del cliente. Consulta Cómo agregar compatibilidad con CORS a un proxy de API. Asegúrate de que CORS también esté habilitado en tu navegador.