Requisitos para integrar una API

En este documento se describen los requisitos generales de una API que quiera añadir como proveedor de tipos a Deployment Manager. Sigue estas directrices para conocer las características de una API que espera Deployment Manager. Si tu API no coincide exactamente con las especificaciones descritas aquí, puedes resolver estas incoherencias mediante las opciones avanzadas de la API.

La API tiene un documento de descriptor válido

Un documento de descriptor describe una API y sus recursos. Solo se pueden integrar con Deployment Manager las APIs que tengan una especificación de OpenAPI o un documento de descriptor de Discovery de Google. Para obtener información detallada sobre cómo crear una especificación de OpenAPI, consulta el repositorio de OpenAPI en GitHub.

Se puede acceder al endpoint del documento de descriptor de la API

Deployment Manager envía una solicitud HTTP para obtener el documento de descriptor de la API, por lo que debes alojar el documento de descriptor en un lugar al que pueda acceder Deployment Manager. Puede ser una URL disponible públicamente o un endpoint protegido por autenticación básica.

La API acepta la autenticación básica o OAuth2 si está alojada en determinados servicios de Google

Actualmente, Deployment Manager admite la autenticación básica (nombre de usuario y contraseña) y la autenticación OAuth 2.0 para determinadas APIs alojadas en Google Kubernetes Engine o en Google Endpoints. Puede configurar la autenticación para usar la cuenta de servicio del proyecto.

Para obtener más información, consulta el artículo Crear un proveedor de tipos.

Admite operaciones de creación, lectura, actualización y eliminación (CRUD)

La API en cuestión debe ser una API RESTful que admita operaciones CRUD. Es decir, hay métodos que realizan las siguientes acciones:

  • Operaciones de creación: crea recursos. Debe ser una solicitud de HTTP POST.
  • Operaciones de lectura: obtiene información sobre los recursos de la API. Debe ser una solicitud de HTTP GET.
  • Operaciones de actualización: actualiza un recurso. Debe ser una solicitud HTTP PUT
  • Eliminar operaciones: elimina recursos. Debe ser una solicitud de HTTP DELETE.

Una API que solo admita operaciones CRUD parciales seguirá funcionando, pero el comportamiento será diferente en función de las operaciones disponibles.

Admite solicitudes GET Admite solicitudes CREATE Admite solicitudes UPDATE Admite solicitudes DELETE ¿Comportamiento especial de la API?
Sí Sí Sí Sí Ninguno
Sí Sí Sí No Los usuarios pueden abandonar un recurso, pero no eliminarlo.
Sí Sí No Sí No se podrá modificar ningún recurso. Los usuarios tendrían que eliminar y volver a crear un recurso para actualizarlo.
Sí Sí No No Ambos comportamientos descritos anteriormente.
Sí No Sí Sí Si una API no admite solicitudes de creación, los usuarios pueden añadir recursos a la implementación actualizando la implementación con la política ACQUIRE.
Sí No Sí No Los usuarios pueden adquirir o actualizar un recurso después de que se haya adquirido, pero no pueden eliminarlo.
Sí No No Sí Los usuarios pueden eliminar un recurso y obtener un recurso, o bien añadir un recurso a una implementación.
Sí No No No Los usuarios pueden adquirir un recurso o quitarlo con la política ABANDON.

Todos los parámetros de ruta y de consulta se resuelven correctamente

Todos los parámetros de ruta y de consulta de la API deben formar parte del cuerpo del recurso o estar presentes en todos los métodos de la API para que Deployment Manager pueda asociar el parámetro cuando un usuario lo proporcione. Las siguientes condiciones se aplican a los parámetros de ruta y de consulta.

Todos los parámetros de ruta o de consulta de un método POST deben ser parámetros de un método PUT

Lo siguiente no es válido porque myParameter existe para POST, pero no para PUT:

POST  /my-api/{myParameter}/resource/{mySecondParameter}
PUT   /my-api/resource/{mySecondParameter}  # myParameter is not present

Todos los parámetros de los métodos que no sean POST deben estar presentes en todas las interfaces de método o formar parte del recurso. Se deben tener en cuenta consideraciones especiales si el servidor genera este parámetro.

En el mejor de los casos, la API podría tener este aspecto, donde el parámetro name aparece en todos los métodos.

POST   /my-api/my-resource/{name}
PUT    /my-api/my-resource/{name}
GET    /my-api/my-resource/{name}
DELETE /my-api/my-resource/{name}

En otro caso, un campo puede aparecer como parámetro de ruta de un método, pero no de otros. En este caso, el campo debe formar parte del recurso de la API. Por ejemplo:

POST  /my-api/my-resource ← the 'id' field  is not present on the POST request
GET   /my-api/my-resource/{id}

schema for my-resource
type: object
properties:
# id is part of the resource so Deployment Manager will use this value for
# POST requests after creation
  id:
    type: string

En este ejemplo, se da por hecho que id es un valor generado por el servidor que está presente en el recurso, pero no cuando se hace una solicitud POST. Si la propiedad id era obligatoria para hacer una solicitud a un recurso, pero no estaba en el recurso o no estaba disponible en la ruta, esto provoca problemas al migrar la API a Deployment Manager.

El comportamiento sutil de la API requiere una configuración adicional

Hay determinados comportamientos de la API que requerirán una configuración adicional para integrar la API con Deployment Manager. Entre estos comportamientos se incluyen los siguientes:

  • Valores generados por el servidor: algunos recursos de la API tienen propiedades generadas por el servidor que cambian después de cada solicitud o cuando se produce un evento determinado en la API. Puede usar opciones avanzadas de la API para indicar a Deployment Manager que obtenga este nuevo valor cada vez que se haga una solicitud.

    Por ejemplo, una API puede requerir la propiedad de huella digital más reciente de un recurso antes de permitir una solicitud de actualización. Usa Opciones avanzadas de la API para indicar a Deployment Manager que obtenga este valor cada vez que el usuario envíe una solicitud para actualizar una implementación con este valor.

  • Manipular la entrada del usuario: por ejemplo, si tu API requiere que el valor de un campo siempre tenga como prefijo un ID de proyecto, puedes usar asignaciones de entrada para añadir esa información automáticamente, en lugar de obligar a los usuarios a añadirla manualmente.

  • Valores de campo que cambian con cada método: en los métodos que reutilizan el mismo campo, pero con valores diferentes, puede usar las opciones de la API para indicar a Deployment Manager cuándo debe usar cada valor.

Para obtener más información, consulta Configurar opciones avanzadas de la API.

Siguientes pasos