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. Renderiza la documentación de referencia de la API desde tu documento de OpenAPI o esquema de GraphQL para que los desarrolladores de apps puedan obtener información sobre tus APIs. (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

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.

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

Console

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 con 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 a minúsculas y sin espacios ni guiones. Por ejemplo: my-org-myportal.

Consulta Notas sobre la paginación para obtener instrucciones sobre el uso de la paginación en la carga útil de la 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 se modificó el elemento del catálogo por última vez, en milisegundos desde la época. Por ejemplo, 1698165480000
  • id: Es el ID del artículo del catálogo. Por ejemplo, 399668

Notas sobre la 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 hay 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:

Console

  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
    Fecha de publicación 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 Publica o anula 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.

    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 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 Administra la visibilidad de una API.

    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. Luego, puedes agregar una imagen como se describe en Administra la imagen para una tarjeta de API. 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.
    Categorías

    Agrega las categorías con las que se etiquetará la API para permitir que los desarrolladores de apps descubran las APIs relacionadas en la página de APIs. 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 agrega a la página Categorías y está disponible cuando se agregan o editan otras APIs.

  7. Haz clic en Guardar.

curl

Para agregar una API a tu portal, sigue estos pasos organizations.sites.apidocs.create:

curl -X POST "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": "IMAGE_URL",
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE,
            "apiProductName": "API_PRODUCT",
         }'

Reemplaza lo siguiente:

  • ORG_NAME por el nombre de la organización. Por ejemplo, my-org.
  • SITE_ID con 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 a minúsculas y sin espacios ni guiones. Por ejemplo: my-org-myportal.
  • TITLE con el título visible. Por ejemplo, Hello World 2
  • DESCRIPTION con la descripción de la pantalla. Por ejemplo, Simple hello world example
  • ANON_TRUE_OR_FALSE con true o false (predeterminado), en el que true habilita el acceso de usuarios anónimos. Esta configuración se ignora si te inscribiste en la versión beta de la función de administración de públicos.
  • IMAGE_URL por la URL de una imagen externa que se usa 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.
  • CALLBACK_TRUE_OR_FALSE por true o false (predeterminado), en el que true requiere que un usuario del portal ingrese una URL cuando administra la app.

  • CATEGORY_ID por el ID de la categoría. Por ejemplo, bf6505eb-2a0f-47af-a00a-ded40ac72960. Separa los distintos IDs de categoría con una coma. Obtén el ID de categoría con el comando categoría list API.

  • PUBLISHED_TRUE_OR_FALSE con true o false (predeterminado), donde true indica que la API está disponible de forma pública.

  • API_PRODUCT con el nombre del producto de API. Por ejemplo, Hello World 2

Respuesta de carga útil:

{
  "status": "success",
  "message": "API created",
  "requestId": "1662161889",
  "data": {
    "siteId": "my-org-myportal",
    "title": "Hello World 2",
    "description": "Simple hello world example",
    "modified": "1698948807000",
    "anonAllowed": true,
    "imageUrl": "/files/book-tree.jpg",
    "id": "409405",
    "requireCallbackUrl": true,
    "categoryIds": [
      "88fbfd1d-9300-49f7-bfc2-531ade4c63d4",
      "630c4cf9-109a-48b0-98cc-ef4c12ae4474"
    ],
    "published": true,
    "apiProductName": "Hello World 2"
  }
}

Aquí:

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

Edita una API

Una vez que hayas agregado una API, usa la consola o una llamada a la API para hacer ediciones.

En esta sección, se proporciona un ejemplo detallado de los pasos que debes seguir para modificar una API existente en tu portal.

Consulta las secciones siguientes para conocer la configuración de modificación específica.

Console

  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. Haz clic en Editar.
  5. En Detalles de la API, realiza las modificaciones necesarias. Consulta las descripciones de las opciones en Agrega una API.
  6. Haz clic en Guardar.

curl

Una vez que hayas agregado una API, usa la llamada organizations.sites.apidocs.update para realizar ediciones.

En este ejemplo, se describen los pasos necesarios para cambiar el estado publicado de tu API en tu portal de true a false. Si es necesario, puedes cambiar más de un parámetro de configuración en una llamada a la API.

  1. Obtén una lista de las API en tu portal a través de organizations.sites.apidocs/list para ubicar el id generado que identifica cada API de forma única:

    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 con 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 a minúsculas y sin espacios ni guiones. Por ejemplo: my-org-myportal.

    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"
    }
  ]
}

    Aquí:

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

  2. Usa la llamada organizations.sites.apidocs.get para devolver los valores actuales de una API específica:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
    -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 con 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 a minúsculas y sin espacios ni guiones. Por ejemplo: my-org-myportal.
    • API_DOC con el id generado del documento. Por ejemplo, 399668. Usa el comando list API docs para encontrar este valor.

    Respuesta de carga útil:

    {
  "status": "success",
  "message": "apidoc returned",
  "requestId": "2072952505",
  "data": {
    "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"
  }
}

  3. Incluye los valores mutables que deseas conservar en la llamada a organizations.sites.apidocs.update y modifica los valores que deseas cambiar. Si omites una línea, se usará la configuración predeterminada. En este ejemplo, cambia el parámetro de configuración published de true a false:

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": "IMAGE_URL",
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": false,
        "apiProductName": "API_PRODUCT",
     }'

    Reemplaza lo siguiente:

    • TITLE con el título visible. Por ejemplo, Hello World 2
    • DESCRIPTION con la descripción de la pantalla. Por ejemplo, Simple hello world example
    • ANON_TRUE_OR_FALSE con true o false (predeterminado), en el que true habilita el acceso de usuarios anónimos. Esta configuración se ignora si te inscribiste en la versión beta de la función de administración de públicos.
    • IMAGE_URL por la URL de una imagen externa que se usa 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.
    • CALLBACK_TRUE_OR_FALSE por true o false (predeterminado), en el que true requiere que un usuario del portal ingrese una URL cuando administra la app.
    • CATEGORY_ID por el ID de la categoría. Por ejemplo, bf6505eb-2a0f-47af-a00a-ded40ac72960. Separa los distintos IDs de categoría con una coma. Obtén el ID de categoría con el comando categoría list API.
    • API_PRODUCT con el nombre del producto de API. Por ejemplo, Hello World 2

    Respuesta de carga útil:

    {
  "status": "success",
  "message": "ApiDoc updated",
  "requestId": "197181831",
  "data": {
    "siteId": "my-org-myportal",
    "title": "Hello World 2",
    "description": "Simple hello world example.",
    "modified": "1698884328000",
    "anonAllowed": true,
    "imageUrl": "/files/book-tree.jpg",
    "id": "408567",
    "requireCallbackUrl": true,
    "categoryIds": [
      "88fbfd1d-9300-49f7-bfc2-531ade4c63d4",
      "630c4cf9-109a-48b0-98cc-ef4c12ae4474"
    ],
    "published": PUBLISHED_TRUE_OR_FALSE,
    "apiProductName": "Hello World 2"
  }
}

Publica o anula la publicación de una API

La publicación es el proceso de hacer que tus API estén disponibles para los desarrolladores de apps.

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

Console

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

curl

Incluye una de las siguientes opciones en la llamada a update:

  "published": true,    # API is published to your portal
  "published": false,   # API is not published in your portal

Para editar la API, sigue estos pasos:

  1. Usa la llamada organizations.sites.apidocs.get para devolver los valores actuales:

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

  2. Usa la llamada organizations.sites.apidocs.update para editar la API. Incluye los valores mutables que deseas conservar y modifica los valores que deseas cambiar. Si omites un parámetro de configuración mutable, se usa el valor predeterminado.

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT",
     }'

Consulta Edita una API para ver un ejemplo detallado de los pasos, las variables y la carga útil que se devuelve.

Administra la visibilidad de una API

Para administrar la visibilidad de una API en tu portal, debes permitir el acceso a lo siguiente:

Para administrar la visibilidad de una API en tu portal, haz lo siguiente:

Console

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

  5. 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 en Visibilidad de la API:

    • 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 en Público:

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

  6. Haz clic en Enviar.

curl

Si te inscribiste en la versión beta de la función de administración de públicos, usa la consola para administrar los públicos.

Si no te inscribiste en la función de administración de públicos, la visibilidad se administra con anonAllowed.

Incluye una de las siguientes opciones en la llamada a update:

  # When not enrolled in the beta release of the audience management feature:

  "anonAllowed": true,      # Anonymous users can see the API
  "anonAllowed": false,     # Only registered users can see the API

Para editar la API, sigue estos pasos:

  1. Usa la llamada organizations.sites.apidocs.get para devolver los valores actuales:

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

  2. Usa la llamada organizations.sites.apidocs.update para editar la API. Incluye los valores mutables que deseas conservar y modifica los valores que deseas cambiar. Si omites un parámetro de configuración mutable, se usa el valor predeterminado.

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT",
     }'

Consulta Edita una API para ver un ejemplo detallado de los pasos, las variables y la carga útil que se devuelve.

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

Console

  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. Haz clic en Editar.
  5. En Detalles de la API, selecciona o borra Se requiere que los desarrolladores especifiquen una URL de devolución de llamada para especificar si se requiere o no una URL de devolución de llamada, respectivamente.
  6. Haz clic en Guardar.

curl

Incluye una de las siguientes opciones en la llamada a update:

  "requireCallbackUrl": true,    # Portal user is required to input a URL
  "requireCallbackUrl": false,   # Portal user is not required to input a URL

Para editar la API, sigue estos pasos:

  1. Usa la llamada organizations.sites.apidocs.get para devolver los valores actuales:

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

  2. Usa la llamada organizations.sites.apidocs.update para editar la API. Incluye los valores mutables que deseas conservar y modifica los valores que deseas cambiar. Si omites un parámetro de configuración mutable, se usa el valor predeterminado.

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT",
     }'

Consulta Edita una API para ver un ejemplo detallado de los pasos, las variables y la carga útil que se devuelve.

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:

Console

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

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

    • Haz clic en Seleccionar imagen para especificar una imagen si no hay ninguna imagen seleccionada.
    • Haz clic en Cambiar imagen para especificar una imagen diferente.
    • 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.

  6. Haz clic en Guardar.

curl

Incluye lo siguiente en la llamada a update:

  # Omit line for no image file

  "imageUrl": "IMAGE_URL"    # URL of the external image or name of the image file

Para editar la API, sigue estos pasos:

  1. Usa la llamada organizations.sites.apidocs.get para devolver los valores actuales:

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

  2. Usa la llamada organizations.sites.apidocs.update para editar la API. Incluye los valores mutables que deseas conservar y modifica los valores que deseas cambiar. Si omites un parámetro de configuración mutable, se usa el valor predeterminado.

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT",
     }'

Consulta Edita una API para ver un ejemplo detallado de los pasos, las variables y la carga útil que se devuelve.

Etiquetar una API a través de categorías

El uso de categorías ayuda a los desarrolladores de apps a descubrir APIs relacionadas. Consulta también Administra categorías.

Para etiquetar una API con categorías, sigue estos pasos:

Console

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

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

  6. Repite para etiquetar la API a más categorías.

  7. Haz clic en Guardar.

curl

Incluye lo siguiente en la llamada a update:

  # Omit line for no categories

  "categoryIds": [
      "CATEGORY_ID1",      # A category ID number
      "CATEGORY_ID2"       # A category ID number
    ],

Usa el comando list categories para obtener los números de ID de categoría.

Para editar la API, sigue estos pasos:

  1. Usa la llamada organizations.sites.apidocs.get para devolver los valores actuales:

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

  2. Usa la llamada organizations.sites.apidocs.update para editar la API. Incluye los valores mutables que deseas conservar y modifica los valores que deseas cambiar. Si omites un parámetro de configuración mutable, se usa el valor predeterminado.

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT",
     }'

Consulta Edita una API para ver un ejemplo detallado de los pasos, las variables y la carga útil que se devuelve.

Edita el título y la descripción visibles

Para editar el título y la descripción de la pantalla, sigue estos pasos:

Console

  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. Haz clic en Editar.
  5. Edita los campos Título para mostrar y Descripción para mostrar, según sea necesario.
  6. Haz clic en Guardar.

curl

Incluye lo siguiente en la llamada a update:

  "title": "TITLE",              # Display title
  "description": "DESCRIPTION",  # Display description

Para editar la API, sigue estos pasos:

  1. Usa la llamada organizations.sites.apidocs.get para devolver los valores actuales:

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

  2. Usa la llamada organizations.sites.apidocs.update para editar la API. Incluye los valores mutables que deseas conservar y modifica los valores que deseas cambiar. Si omites un parámetro de configuración mutable, se usa el valor predeterminado.

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT",
     }'

Consulta Edita una API para ver un ejemplo detallado de los pasos, las variables y la carga útil que se devuelve.

Quita una API

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

Console

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

curl

Para quitar una API de tu portal, sigue estos pasos organizations.sites.apidocs.delete:

curl -X DELETE "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
    -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 con 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 a minúsculas y sin espacios ni guiones. Por ejemplo: my-org-myportal.
  • API_DOC con el id generado del documento. Por ejemplo, 399668. Usa el comando list API docs para encontrar este valor.

Respuesta de carga útil:

{
  "status":"success",
  "message":"Apidoc deleted",
  "requestId":"645138256"
}

Administra la documentación de la API

En las siguientes secciones, se describe cómo actualizar, descargar o quitar la documentación de la API.

Actualiza la documentación de la API

Después de publicar la API, puedes subir una versión nueva del documento de OpenAPI o GraphQL en cualquier momento.

Para subir una versión diferente de la documentación de la API, sigue estos pasos:

Console

  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. Haz clic en Editar.
  5. En el panel Documentación de la API, selecciona una de las siguientes opciones:
    • Documento de OpenAPI
    • Esquema de GraphQL
  6. Haz clic en Seleccionar documento y selecciona la versión más reciente del documento.
  7. Para GraphQL, especifica la URL de extremo.
  8. Haz clic en Guardar.

curl

Para actualizar el contenido de la documentación de OpenAPI o GraphQL con organizations.sites.apidocs.updateDocumentation, haz lo siguiente:

OpenAPI

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"oasDocumentation": {
           "spec":{ "displayName":"DISPLAY_NAME",
                    "contents":"CONTENTS"}
            }
        }'

Reemplaza lo siguiente:

  • ORG_NAME por el nombre de la organización. Por ejemplo, my-org.
  • SITE_ID con 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 a minúsculas y sin espacios ni guiones. Por ejemplo: my-org-myportal.
  • API_DOC con el id generado del documento. Por ejemplo, 399668. Usa el comando list API docs para encontrar este valor.
  • DISPLAY_NAME por el nombre visible de la documentación de la API. Por ejemplo, Hello World 2.
  • CONTENTS por la cadena de contenido codificada en Base64 de la documentación de la API. La mayoría de los entornos de desarrollo contienen una utilidad de conversión base64, o bien hay muchas herramientas de conversión en línea.

Respuesta de carga útil:

{
 "status":"success",
 "message":"Api documentation updated",
 "requestId":"645138278"
 "data": {
   "oasDocumentation": {
     "spec": {
        "displayName": "Hello World 2"
      },
     "Format": "YAML"
   }
 }
}

GraphQL

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"graphqlDocumentation": {
         "schema":{"displayName":"DISPLAY_NAME",
         "contents":"CONTENTS"},
         "endpointUri": "ENDPOINT_URI"
          }
      }'

Reemplaza lo siguiente:

  • ORG_NAME por el nombre de la organización. Por ejemplo, my-org.
  • SITE_ID con 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 a minúsculas y sin espacios ni guiones. Por ejemplo: my-org-myportal.
  • API_DOC con el id generado del documento. Por ejemplo, 399668. Usa el comando list API docs para encontrar este valor.
  • DISPLAY_NAME por el nombre visible de la documentación de la API. Por ejemplo, Hello World 2.
  • ENDPOINT_URI por el nombre de dominio del URI de tu extremo. Por ejemplo, https://demo.google.com/graphql
  • CONTENTS por la cadena de contenido codificada en Base64 de la documentación de la API. La mayoría de los entornos de desarrollo contienen una utilidad de conversión base64, o bien hay muchas herramientas de conversión en línea.

Respuesta de carga útil:

{
 "status":"success",
 "message":"Api documentation updated",
 "requestId":"645138278"
  "data": {
    "graphqlDocumentation": {
      "schema": {
        "displayName": "Hello World 2"
      },
     "endpointUri": "https://demo.google.com/graphql"
    }
  }
}

La documentación de referencia de la API se renderiza desde el documento y se agrega a la página de APIs del portal publicado.

Descarga la documentación de la API

Después de publicar la API, puedes descargar la documentación de referencia de OpenAPI o GraphQL que se publica en tu portal en cualquier momento.

Para descargar la documentación de la API a través de organizations.sites.apidocs.getDocumentation, haz lo siguiente:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -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 con 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 a minúsculas y sin espacios ni guiones. Por ejemplo: my-org-myportal.

  • API_DOC con el id generado del documento. Por ejemplo, 399668. Usa el comando list API docs para encontrar este valor.

    Respuesta de carga útil:

{
  "status":"success",
  "message":"Api documentation downloaded",
  "requestId":"645138256",
  "data": {
      "oasDocumentation":{
          "spec":{
            "displayName":"Hello World 2",
            "contents":"c3dhZ2dlcjogJzIuMCcKaW5mbzoKICBkZXNlI ..."
          },
          "Format": YAML
      }
  }
}

Aquí:

contents:: Es la cadena de contenido codificada en Base64 de la documentación de la API.

Quita la documentación de la API

Para quitar la documentación de la API, sigue estos pasos:

Console

  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. Haz clic en Editar.
  5. En el panel Documentación de la API, selecciona Sin documentación.
  6. Haz clic en Guardar.

curl

Para quitar el contenido de un documento de API a través de una API, envía un cuerpo de solicitud vacío para borrar la configuración existente.

Para enviar un cuerpo de solicitud vacío y borrar el contenido existente con organizations.sites.apidocs.updateDocumentation, haz lo siguiente:

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{}'

Reemplaza lo siguiente:

  • ORG_NAME por el nombre de la organización. Por ejemplo, my-org.
  • SITE_ID con 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 a minúsculas y sin espacios ni guiones. Por ejemplo: my-org-myportal.
  • API_DOC con el id generado del documento. Por ejemplo, 399668. Usa el comando list API docs para encontrar este valor.

Respuesta de carga útil:

{
   "status":"success",
   "message":"Api documentation updated",
   "requestId":"645138279"
}

Administrar categorías

Etiqueta una API con 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 las categorías

Usa la consola o el comando curl para ver las categorías.

Console

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

  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.

    Pestaña Categorías que muestra el nombre de la categoría, los nombres y la cantidad total de API asignadas

    Pestaña Categorías que muestra el nombre de la categoría, los nombres y la cantidad total de API asignadas

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

curl

Para enumerar categorías a través de organizations.sites.apicategories.list, haz lo siguiente:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -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 con 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 a minúsculas y sin espacios ni guiones. Por ejemplo: my-org-myportal.

Respuesta de carga útil:

{
  "data": [
    {
      "siteId": "my-org-myportal",
      "name": "Get Started",
      "id": "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
    },
    {
      "siteId": "my-org-myportal",
      "name": "Test",
      "id": "61c1014c-89c9-40e6-be3c-69cca3505620"
    }
  ],
  "status": "success",
  "message": "all ApiCategory items returned",
  "requestId": "602661435"
}

Aquí:

  • id: Es el ID del artículo de la categoría. Por ejemplo, 61c1014c-89c9-40e6-be3c-69cca3505620

Agregar una categoría

Para agregar una categoría:

Console

  1. Accede a la página Categorías.
  2. Haga clic en Agregar.
  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.

curl

Para agregar una categoría con organizations.sites.apicategories.create, haz lo siguiente:

curl  -X POST "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

Reemplaza lo siguiente:

  • ORG_NAME por el nombre de la organización. Por ejemplo, my-org.
  • SITE_ID con 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 a minúsculas y sin espacios ni guiones. Por ejemplo: my-org-myportal.
  • CATEGORY_NAME por el nombre de la categoría. Por ejemplo, demo-backend

Respuesta de carga útil:

{
  "data": {
    "siteId": "my-org-myportal",
    "name": "demo-backend",
    "id": "ed0b6c1d-eb49-419f-8475-9a428ed5b8d1"
  },
  "status": "success",
  "message": "API category created",
  "requestId": "295617049"
}

Editar una categoría

Para editar una categoría, sigue estos pasos:

Console

  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 Editar.
  4. Edita el nombre de la categoría.
  5. Agrega o quita etiquetas de API
  6. Haz clic en Guardar.

curl

Para editar una categoría con organizations.sites.apicategories.patch, haz lo siguiente:

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID"  \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

Reemplaza lo siguiente:

  • ORG_NAME por el nombre de la organización. Por ejemplo, my-org.
  • SITE_ID con 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 a minúsculas y sin espacios ni guiones. Por ejemplo: my-org-myportal.
  • CATEGORY_ID por el ID de la categoría. Por ejemplo, bf6505eb-2a0f-47af-a00a-ded40ac72960. Obtén el ID de categoría con el comando categoría list API.
  • CATEGORY_NAME por el nombre de la categoría. Por ejemplo, demo-backend

Respuesta de carga útil:

{
  "data": {
    "siteId": "my-org-myportal",
    "name": "demo-backend-test",
    "id": "ed0b6c1d-eb49-419f-8475-9a428ed5b8d1"
  },
  "status": "success",
  "message": "ApiCategory updated",
  "requestId": "192211979"
}

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:

Console

  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 Borrar.
  4. Haz clic en Borrar para confirmar tu decisión.

curl

Para borrar una categoría con organizations.sites.apicategories.delete, haz lo siguiente:

curl -X DELETE "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json"

Reemplaza lo siguiente:

  • ORG_NAME por el nombre de la organización. Por ejemplo, my-org.
  • SITE_ID con 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 a minúsculas y sin espacios ni guiones. Por ejemplo: my-org-myportal.
  • CATEGORY_ID por el ID de la categoría. Por ejemplo, bf6505eb-2a0f-47af-a00a-ded40ac72960. Obtén el ID de categoría con el comando categoría list API.

Respuesta de carga útil:

{
  "status": "success",
  "message": "ApiCategory deleted",
  "requestId": "1610396471"
}

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 devolvió cuando se usó la API

Cuando uses Prueba esta API, 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 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 la sección sobre cómo configurar el proxy de API para admitir el panel de esta API.

Error: No se permite el campo del encabezado de la solicitud

Cuando se usa Prueba 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:

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 con OAuth 2.0

La política OAuthV2 de la consola de Google Cloud devuelve una respuesta de token que contiene ciertas propiedades que no cumplen con RFC. Por ejemplo, la política devolverá 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 Prueba esta API.

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.