Publicar tus API

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Publica las API en tu portal para 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 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, consulta Acerca de la documentación de la API)

¿Qué se publica en el portal?

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

  • 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. Ver:
  • 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 para 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 APIs que permiten a los desarrolladores descubrir APIs relacionadas en la página de las APIs
    Página de APIs del portal en vivo que muestra dos categorías y el uso de imágenes Página de APIs del portal en vivo que muestra dos categorías y el uso de imágenes

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.

Página de documentación de referencia de la API con solicitudes de oferta que muestran cómo autorizar tu llamada a la API, deshacer el panel Prueba esta API, descargar la especificación relevante y ejecutar la API.

Página de documentación de referencia de la API con solicitudes de oferta que muestran cómo autorizar tu llamada a la API, deshacer el panel Prueba esta API, descargar la especificación relevante y ejecutar la API.

Haz clic en Pantalla completa 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.

Panel ampliado de la sección Prueba esta API

Panel ampliado de la sección Prueba esta API

Explorador de GraphQL

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.

GraphQL Explorer en el portal

GraphQL Explorer en el portal

Acerca de la documentación de la API

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 en un portal, guardas una versión del documento de OpenAPI o GraphQL para procesar la documentación de referencia de la API. Si modificas el documento, puedes decidir actualizar la documentación de referencia de la API publicada en el portal para reflejar los cambios más recientes.

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 en general 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, 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 API que la requieren, como se describe en la sección sobre cómo registrar apps.

Configura el proxy de API para que admita el panel 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 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 OAuth 2.0.

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 API, sigue los pasos descritos en Cómo agregar compatibilidad con CORS a un proxy de API.
Autenticación básica Sigue los siguientes pasos:
  1. Agregar compatibilidad con CORS al proxy de API; sigue los pasos que se describen en Cómo agregar compatibilidad con CORS a un proxy de API.
  2. En Agregar política 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>
OAuth 2.0
  1. Agregar compatibilidad con CORS al proxy de API; sigue los pasos que se describen en Cómo agregar compatibilidad con CORS a un proxy de API.
  2. En Agregar política 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>
  3. Corrige el comportamiento que no cumple con RFC en la política de OAuth 2.0. Para mayor comodidad, usa la solución OAuth 2.0 de muestra proporcionada en GitHub o realiza los siguientes pasos:
    • Asegúrate de que el elemento <GrantType> de la política OAuth 2.0 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 OAuth 2.0 esté configurado en Bearer y no el BearerToken predeterminado.

Administra APIs

Administra tus APIs como se describe en las siguientes secciones.

Ver todas las APIs

Usa la consola o el comando curl para ver las APIs que se encuentran en tu portal.

Consola

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 APIs del catálogo de APIs muestra una lista de las APIs que se agregaron a tu portal.

    Pestaña APIs que muestra información sobre las APIs, como el nombre, la descripción, la visibilidad, las categorías, las especificaciones asociadas y la hora modificada

    Pestaña APIs que muestra información sobre las APIs, como el nombre, la descripción, la visibilidad, las categorías, las especificaciones asociadas y la hora modificada

    Como se destacó en la figura anterior, la pestaña de APIs te permite hacer lo siguiente:

curl

Para enumerar las APIs a través de organizations.sites.apidocs/list, haz lo siguiente:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Reemplaza lo siguiente:

  • ORG_NAME por el nombre de la organización. Por ejemplo, my-org.
  • SITE_ID por el nombre del portal, en el formato ORG_NAME-PORTAL_NAME, en el que ORG_NAME es el nombre de la organización y PORTAL_NAME es el nombre del portal convertido en todo en minúsculas y sin espacios ni guiones. Por ejemplo: my-org-myportal.

Consulta Notas de paginación para obtener instrucciones sobre el uso de la paginación en la carga útil de respuesta.

Respuesta de carga útil:

{
  "status": "success",
  "message": "one page of apidocs returned",
  "requestId": "1167960478",
  "data": [
    {
      "siteId": "my-org-myportal",
      "title": "Hello New World",
      "description": "Simple hello new world example",
      "specId": "hellowworld",
      "modified": "1695841621000",
      "anonAllowed": true,
      "imageUrl": "/files/camper1.jpg?v=1695841491415",
      "id": "381054",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello New World"
    },
    {
      "siteId": "my-org-myportal",
      "title": "mock-product",
      "description": "Mock product",
      "specId": "apigee spec",
      "modified": "1698956849000",
      "anonAllowed": true,
      "id": "399638",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
      ],
      "published": true,
      "apiProductName": "mock-product"
    },
    {
      "siteId": "my-org-myportal",
      "title": "Hello World 2",
      "description": "Simple hello world example",
      "specId": "hello-new-world",
      "modified": "1698950207000",
      "anonAllowed": true,
      "imageUrl": "/files/book-tree.jpg?v=1698165437881",
      "id": "399668",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello World 2"
    }
  ],
  "nextPageToken": ""
}

Aquí:

  • modified:: Es la hora en que el elemento del catálogo se modificó por última vez en milisegundos desde el ciclo. Por ejemplo, 1698165480000
  • id:: Es el ID del elemento del catálogo. Por ejemplo, 399668

Notas de paginación:

  • Tamaño de la página: Usa pageSize para especificar la cantidad de elementos de la lista que se devolverán en una página. El valor predeterminado es 25 y el máximo es 100. Si hay páginas adicionales, nextPageToken se propaga con un token:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE" \
       -H "Authorization: Bearer $(gcloud auth print-access-token)"
    

    Reemplaza lo siguiente:

    • PAGE_SIZE por el número de elementos de lista que se devuelven en una página. Por ejemplo, 10

    Respuesta de carga útil:

    {
      "status": "success",
      "message": "one page of apidocs returned",
      "requestId": "918815495",
      "data": [
        {
          "siteId": "my-org-myportal",
          "title": "Hello New World",
          "description": "Simple hello new world example",
          "specId": "apigee",
          "modified": "1699146887000",
          "anonAllowed": true,
          "imageUrl": "/files/camper1.jpg?v=1695841491415",
          "id": "381054",
          "categoryIds": [
            "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
            "61c1014c-89c9-40e6-be3c-69cca3505620"
          ],
          "published": true,
          "apiProductName": "Hello New World"
        }
      ],
      "nextPageToken": "7zcqrin9l6xhi4nbrb9"
    }
    
  • Página de token:

    Usa pageToken para recuperar páginas posteriores cuando haya más de una:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN" \
          -H "Authorization: Bearer $(gcloud auth print-access-token)"
    

    Reemplaza lo siguiente:

    • PAGE_SIZE por el número de elementos de lista que se devuelven en una página. Por ejemplo, 10
    • PAGE_TOKEN con el valor nextPageToken Por ejemplo, 7zcqrin9l6xhi4nbrb9.

Agrega una API

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

Consola

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

    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. Haz clic en Siguiente. 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
    Publicada Selecciona Publicado 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 Publicar o anular la publicación de una API.
    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 del visualización 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 la sección sobre cómo administrar la URL de devolución de llamada de una API.
    Documentación de la API

    Para usar un documento de OpenAPI, sigue estos pasos:

    1. Selecciona Documento de OpenAPI.
    2. Haz clic en Seleccionar documento.
    3. Realiza uno de los siguientes pasos:
      • Haz clic en la pestaña Subir archivo y sube un archivo.
      • Haz clic en la pestaña Importar desde una URL y también importa una especificación. Para ello, proporciona un nombre y una URL desde la cual importar.
    4. Haz clic en Seleccionar.

    Para usar un esquema de GraphQL, haz lo siguiente:

    1. Selecciona Esquema de GraphQL.
    2. Haz clic en Seleccionar documento.
    3. Navega hasta el esquema de GraphQL y selecciónalo.
    4. Haz clic en Seleccionar.

    También puedes seleccionar Sin documentación y agregar una más tarde, después de agregar la API, como se describe en Administra la documentación de la API.

    Visibilidad

    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.