Requisitos de API para su integración

En este documento se describen los requisitos generales de una API que deseas agregar como un proveedor de tipos a Deployment Manager. Utiliza estos lineamientos para comprender las características de una API que espera Deployment Manager. Si la API no coincide exactamente con las especificaciones que se describen aquí, es posible que puedas resolver estas inconsistencias con el uso de las Opciones de API avanzadas.

La API tiene un documento descriptor válido

Un documento descriptor describe una API y sus recursos. Solo las API respaldadas por una especificación de OpenAPI o un documento descriptor de Google Discovery pueden integrarse en Deployment Manager. Para obtener información completa sobre cómo crear una especificación de OpenAPI, consulta el repositorio de GitHub de OpenAPI.

Se puede acceder al extremo del documento descriptor de la API

Deployment Manager realiza una solicitud HTTP para obtener el documento descriptor de la API, por lo que debes asegurarte de alojar el documento descriptor en algún lugar al que Deployment Manager pueda acceder. Puede ser una URL disponible de forma pública o un extremo que esté protegido por una autenticación básica.

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

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

Para obtener más información, lee Crea 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 de RESTful que admita operaciones de CRUD. Es decir, hay métodos que llevan a cabo las siguientes operaciones:

  • Operaciones de creación: se crean recursos. Debe ser una solicitud HTTP POST.
  • Operaciones de lectura: se obtiene información sobre los recursos de la API. Debe ser una solicitud HTTP GET.
  • Operaciones de actualización: se actualiza un recurso. Debe ser una solicitud HTTP PUT
  • Operaciones de borrado: se borran recursos. Debe ser una solicitud HTTP DELETE.

Una API que solo admite operaciones parciales de CRUD seguirá funcionando, pero el comportamiento será diferente según las operaciones disponibles.

Admite solicitudes GET Admite solicitudes CREATE Admite solicitudes UPDATE Admite solicitudes DELETE ¿Comportamiento especial de la API?
Sí Sí Sí Sí Ninguna
Sí Sí Sí No. Los usuarios pueden abandonar un recurso, pero no pueden borrarlo.
Sí Sí No. Sí Cualquier cambio en un recurso existente tendría errores. Los usuarios tendrían que borrar y volver a crear un recurso para actualizarlo.
Sí Sí No. No. Ambos comportamientos se describieron anteriormente.
Sí No. Sí Sí Si una API no admite solicitudes de creación, los usuarios pueden agregar los recursos existentes a la implementación; para ello, se debe actualizar la implementación con la política ACQUIRE.
Sí No. Sí No Los usuarios pueden adquirir un recurso o actualizar un recurso después de que se haya adquirido, pero el recurso no puede borrarse.
Sí No. No. Sí Los usuarios pueden borrar un recurso y obtener un recurso, o pueden agregar un recurso existente a una implementación.
Sí No. No. No. Los usuarios pueden adquirir un recurso existente o quitarlo con la política ABANDON.

Todos los parámetros de ruta y búsqueda se resuelven correctamente

Todos los parámetros de ruta y búsqueda de la API deben existir como parte del cuerpo del recurso o existir en todos los métodos de la API, de modo que Deployment Manager pueda coincidir con el parámetro cuando un usuario lo proporcione. Las siguientes condiciones se aplican a los parámetros de ruta y búsqueda.

Cada parámetro de ruta o búsqueda para un POST debe ser un parámetro para PUT

La siguiente información no es válida porque myParameter existe para POST, pero no para PUT:

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

Cada parámetro para un método que no sea POST debe estar presente en todas las interfaces del método, o como parte del recurso, con consideraciones especiales si el servidor genera este parámetro.

En el mejor de los casos, la API podría tener este aspecto, en el que el parámetro name aparece para 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 otra situación, un campo podría aparecer como un parámetro de ruta para un método, pero no como un parámetro de ruta para otros métodos. En este caso, el campo debe ser 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 supone que id es un valor generado por el servidor que está presente en el recurso, pero no aparece cuando se realiza una solicitud POST. Si se requirió la propiedad id para realizar una solicitud a un recurso existente, pero la propiedad no estaba en el recurso o no estaba disponible en la ruta, esto causa fricción cuando se transfiere la API a Deployment Manager.

El comportamiento sutil de la API requiere configuración adicional

Existen ciertos comportamientos de la API que requerirán una configuración adicional de la API para integrarla con Deployment Manager. Esto es lo que incluyen estos comportamientos:

  • 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 ocurre un evento determinado en la API. Puedes utilizar opciones de API avanzadas para indicarle a Deployment Manager que obtenga este valor nuevo cada vez que se realiza una solicitud.

    Por ejemplo, una API podría requerir la última propiedad de huella digital de un recurso antes de permitir una solicitud de actualización. Utiliza las Opciones de API avanzadas para indicarle a Deployment Manager que obtenga este valor cada vez que tu usuario realice una solicitud para actualizar una implementación con este valor.

  • Manipulación de la entrada del usuario: por ejemplo, si la API requiere que el valor de un campo siempre debe estar prefijado con el ID del proyecto, puedes usar las asignaciones de entrada para agregar de forma automática esa información, en lugar de obligar a los usuarios a agregarla de forma manual.

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

Para obtener más información, lee sobre las Configura las opciones de API avanzadas.

¿Qué sigue?