Recomendaciones para agregar un proveedor de tipos

En esta página se describen recomendaciones para crear una nueva API para agregar a Deployment Manager como Proveedor de tipos, o agregar una API existente como proveedor de tipos.

Deployment Manager te permite agregar API como proveedores de tipos a fin de exponer los recursos de la API como tipos que puedes llamar en su configuración. Para facilitarte el proceso, utiliza estas recomendaciones cuando configures o crees una API.

Compilar una nueva API

Si estás compilando una nueva API que pretendes integrar con Deployment Manager, utiliza estas recomendaciones.

Usa métodos Crea, lee, actualiza y elimina (CRUD), y evita los métodos personalizados

De ser posible, evita crear métodos personalizados. Utiliza métodos REST como GET, POST, PUT, y métodos DELETE. Deployment Manager reconoce estos métodos y puede asignarlos automáticamente.

Para las API de descubrimiento, deberías nombrar a los métodos de tu API en función de las siguientes asginaciones:

Método REST Nombre de API recomendado
POST create o insert
GET get
PUT update
DELETE delete

Para las especificaciones OpenAPI, los nombres de los métodos de tu API no pueden ser diferentes a los métodos REST estándar.

Usa rutas de recursos predecibles

Para las especificaciones OpenAPI, Deployment Manager admite dos comportamientos que identifiquen una interfaz RESTful. El primero es si todos los métodos REST de un recurso pertenecen a la misma ruta del recurso:

/foo/{name}
  post:
  get:
  delete:
  put:

Si debes separar los métodos, utiliza la misma ruta del recurso: Por ejemplo, la siguiente es válida porque hace referencia al mismo recurso /foo:

/foo/
  post:
/foo/{id}
  get:
  delete:
  put:

Sin embargo, la siguiente no es válida, ya que hace referencia a dos recursos diferentes de una vista de Deployment Manager:

/foo/
 post:
/foo-bar/{id}:
 get:
 put:
 delete:

En casos excepcionales, es posible que quieras nombrar las rutas de tus recursos de la siguiente manera:

foo/create
  post:

foo/delete
  delete:

Esto no es válido desde la vista de Deployment Manager, ya que no puede identificar la interfaz RESTful.

Usa nombres coherentes en la interfaz

Asegúrate de que los nombres de entrada y de la ruta sean los mismos entre los métodos POST y PUT. Esto también se aplica a los valores de parámetros. Es decir, que la sintaxis de los valores de parámetros sea la misma en todos los métodos.

Por ejemplo, si tienes un parámetro denominado email para el cuerpo de la solicitud POST, no nombres el mismo parámetro emailAddress para la solicitud PUT.

POST
{
    “email”: “my-email”
}

PUT
{
    “email”: “my-email@gmail.com”
}

Si tienes que agregar este tipo de comportamiento, para indicarle a Deployment Manager cómo administrar este comportamiento establece opciones avanzadas de la API.

Además, el cuerpo de la solicitud para los métodos POST y PUT debería ser el mismo. Para los métodos GET y DELETE, solo la ruta es aplicable ya que no hay un cuerpo de solicitud para estos métodos.

Integra una API existente

La integración de una API existente puede ser un proceso muy variado que depende de la API. Como tal, no existe un conjunto de recomendaciones concreto que pueda aplicarse de forma generalizada en todas las API. A continuación, se presenta una lista de consejos generales que podrían ser de ayuda para la integración de una API existente.

  • Utiliza un wrapper de API para API que no sean de RESTful.

    Si una API existente no es una API de RESTful, puedes crear un wrapper de API a fin de exponer solamente los métodos REST.

  • Si la API es casi RESTful, identifica y actualiza la API.

    Si tu API es casi RESTful y solamente tiene algunos comportamientos que no sean REST, puedes actualizarla y resolver esos comportamientos.

  • Los valores generados por el servidor siempre requieren una asignación de entradas.

    Si tu API tiene valores generados por el servidor que se requieren en los métodos de la API, deberás establecer asignaciones de entradas a fin de obtener el valor generado por el servidor y asignarlo a cada solicitud.

¿Qué sigue?