Publica tus API

Estás consultando la documentación de Apigee Edge.
Consulta 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:

1. Selecciona el producto de API que deseas publicar en tu portal.
2. 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, se realizan las siguientes actualizaciones en tu portal de forma automática:

Documentación de referencia de la API. La interfaz proporcionada depende de si publicas tu API con un documento de OpenAPI o un esquema de GraphQL. Consulta lo siguiente:

• SmartDocs (OpenAPI)
• Explorador de GraphQL

Se agrega un vínculo a la página de referencia de la API.

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 esta configuración en cualquier momento, tal como se describe en Cómo administrar la URL de devolución de llamada para una API.

Cuando registran una app, los desarrolladores deben ingresar una URL de devolución de llamada para todas las APIs que la requieran, como se describe en Registra apps.

Configura tu proxy de API para que admita la opción "Prueba 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:

• Agrega compatibilidad con CORS a tus proxies de API para aplicar 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 de implementación general para la "política de 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 estos pasos: 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. En Agregar política AssignMessage de CORS, asegúrate de que el encabezado Access-Control-Allow-Headers incluya el atributo authorization. Por ejemplo: <Header name="Access-Control-Allow-Headers"> origin, x-requested-with, accept, content-type, authorization </Header>
OAuth2	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. En Agregar política AssignMessage de CORS, asegúrate de que el encabezado Access-Control-Allow-Headers incluya el atributo authorization. Por ejemplo: <Header name="Access-Control-Allow-Headers"> origin, x-requested-with, accept, content-type, authorization </Header> Corrige el comportamiento que no cumple con RFC en la política de OAuth2. Para mayor comodidad, usa la solución OAuth2 de muestra proporcionada en GitHub o realiza los siguientes pasos: Asegúrate de que el elemento <GrantType> de la política OAuth2 esté configurado como request.formparam.grant_type (parámetro de formulario). Para obtener más información, consulta <GrantType>. Asegúrate de que el token_type de la política de OAuth2 esté configurado en Bearer y no el BearerToken predeterminado.

Explora el catálogo de APIs

Para ver el catálogo de la API, haz lo siguiente:
1. Selecciona Publicar > Portales y selecciona tu portal.
2. 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.

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.
  • Publica una API en tu portal o anula su publicación
  • 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.
• Identifica rápidamente las APIs “huérfanas” cuyo producto de API asociado se quitó de Edge y vuelve a crear el producto de API o borra la API de tu portal

Agrega una API a tu portal

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

1. Accede al catálogo de API.
2. Haz clic en la pestaña API si no está seleccionada.

3. Haz clic en +.

   Se muestra el cuadro de diálogo Agregar producto de API al catálogo.

4. Selecciona el producto de API que quieres agregar a tu portal.

5. Haga clic en Next.
   Se mostrará la página de detalles de la API.

6. Configura el contenido de la documentación de referencia de la API y su visibilidad en el portal:

   Campo	Descripción
   Publicado	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 Cómo publicar o anular 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 más adelante según se indica en Cómo editar el título y la descripción.
   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 más adelante según se indica en Cómo editar 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 adelante, según se describe en Cómo administrar 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. También puedes seleccionar Sin documentación y agregar una más adelante después de agregar la API, según se describe en Cómo administrar 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 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 adelante, como se describe en Cómo administrar la imagen para una tarjeta de API.
   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.

7. Haz clic en Guardar.

Administrar 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:

1. Accede al catálogo de APIs.
2. Haz clic en la pestaña APIs si no está seleccionada.
3. Haz clic en la fila de la API que quieres editar.
4. Verifica el estado de la instantánea. Si está desactualizado, se muestra el siguiente mensaje:
   
5. Haz clic en .
6. Realiza una de las siguientes tareas:
   • Para actualizar una instantánea de un documento de OpenAPI que esté desactualizado, haz clic en Refresh Snapshot.
   • Para cambiar el documento que se usa para generar la documentación de la API, debajo de API document, haz clic en Select Document y selecciona el documento nuevo.
7. 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 una API en tu portal o anula su publicación

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

1. Accede al catálogo de API.
2. Haz clic en la pestaña APIs si no está seleccionada.
3. Haz clic en la fila de la API que quieres editar.
4. Haz clic en .
5. 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.
6. 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:

1. Accede al catálogo de API.
2. Haz clic en la pestaña APIs si no está seleccionada.
3. Haz clic en la fila de la API que quieres editar.
4. Haz clic en .
5. En la visibilidad de la API, selecciona una de las siguientes opciones:

6. 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.
   De lo contrario, selecciona una de las siguientes opciones:
   • Usuarios anónimos para que todos los usuarios vean la página.
   • Usuarios registrados para que solo los usuarios registrados vean la página.

7. 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

1. Accede al catálogo de API.
2. Haz clic en la pestaña APIs si no está seleccionada.
3. Haz clic en la fila de la API que quieres editar.
4. Haz clic en .
5. 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.
6. 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:

1. Accede al catálogo de API.
2. Haz clic en la pestaña APIs si no está seleccionada.
3. Haz clic en la fila de la API que quieres editar.
4. Haz clic en .

5. En los detalles de API, haz lo siguiente:

   • Haz clic en Seleccionar imagen para elegir o subir una imagen si no hay ninguna imagen seleccionada.
   • Haz clic en Cambiar imagen para seleccionar o subir una imagen diferente.
   • Haz clic en x en la imagen para quitarla.

6. 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:

1. Accede al catálogo de API.
2. Haz clic en la pestaña APIs si no está seleccionada.
3. Haz clic en la fila de la API que quieres editar.
4. Haga clic en .
5. 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.
6. Repite para etiquetar la API a más categorías.
7. 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:

1. Accede al catálogo de API.
2. Haz clic en la pestaña APIs si no está seleccionada.
3. Haz clic en la fila de la API que quieres editar.
4. Haga clic en .
5. Edita los campos Título para mostrar y Descripción para mostrar, según sea necesario.
6. Haz clic en Guardar.

Quita una API de tu portal

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

1. Accede al catálogo de API.
2. Selecciona las API si aún no lo están.
3. Coloca el cursor sobre la API de la lista para ver el menú de acciones.
4. Haz clic en .

Administra las categorías utilizadas 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:

1. Selecciona Publicar > Portales y selecciona tu portal.
2. 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.

3. 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 imagen anterior, la página 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:

1. Accede a la página Categorías.
2. Haz clic en +.
3. Ingresa el nombre de la nueva categoría.
4. De manera opcional, selecciona una o más API que quieras etiquetar a la categoría.
5. Haz clic en Crear.

Editar una categoría

Para editar una categoría, sigue estos pasos:

1. Accede a la página Categorías.
2. Haga clic en .
3. Edita el nombre de la categoría.
4. Agrega o quita etiquetas de API
5. 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:

1. Accede a la página Categorías.
2. Coloca el cursor sobre la categoría que quieras editar para que se muestre el menú de acciones.
3. Haz clic en .
4. Edita el nombre de la categoría.
5. Agrega o quita API
6. 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 admitir la opción Prueba 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.