Prácticas recomendadas para añadir proveedores de tipos

En esta página se describen las prácticas recomendadas para crear una API que se va a añadir a Deployment Manager como proveedor de tipos o para añadir una API que ya exista como proveedor de tipos.

Deployment Manager te permite añadir APIs como proveedores de tipos para exponer los recursos de la API como tipos a los que puedes llamar en su configuración. Para facilitarte el proceso, sigue estas prácticas recomendadas al configurar o crear una API.

Crear una API

Si vas a crear una API nueva que quieras integrar con Deployment Manager, sigue estas prácticas recomendadas.

Usar métodos estándar de creación, lectura, actualización y eliminación (CRUD) y evitar los métodos personalizados

Evita crear métodos personalizados siempre que sea posible. Utiliza métodos REST estándar, como GET, POST, PUT y DELETE. Deployment Manager reconoce estos métodos y se pueden asignar automáticamente.

En el caso de las APIs de Discovery, debes asignar nombres a los métodos de la API según la siguiente asignación:

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

En el caso de las especificaciones de OpenAPI, no puede asignar a los métodos de la API nombres distintos de los métodos REST estándar.

Usar rutas de recursos predecibles

En el caso de las especificaciones de OpenAPI, Deployment Manager admite dos comportamientos para identificar una interfaz RESTful. La primera es si todos los métodos REST de un recurso pertenecen a la misma ruta de recurso:

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

Si debes separar los métodos, usa la misma ruta de recurso. Por ejemplo, el siguiente es válido porque hace referencia al mismo recurso /foo:

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

Sin embargo, lo siguiente no es válido porque hace referencia a dos recursos diferentes desde el punto de vista de Deployment Manager:

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

En casos excepcionales, puede que te veas tentado a asignar nombres a tus rutas de recursos de la siguiente manera:

foo/create
  post:

foo/delete
  delete:

No es válido desde el punto de vista de Deployment Manager porque no puede identificar la interfaz RESTful.

Usar nombres coherentes en toda la interfaz

Mantén los mismos nombres de entrada y de ruta entre los métodos POST y PUT. Esto también se aplica a los valores de los parámetros. Es decir, mantén la misma sintaxis para los valores de los parámetros en todos los métodos.

Por ejemplo, si tiene un parámetro llamado email para el cuerpo de la solicitud de una solicitud POST, no le asigne el mismo nombre (emailAddress) a la solicitud PUT.

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

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

Si debes añadir este tipo de comportamiento, indica a Deployment Manager cómo gestionarlo configurando las opciones avanzadas de la API.

Además, mantén el mismo cuerpo de solicitud para los métodos POST y PUT. En el caso de los métodos GET y DELETE, solo se aplica la ruta, ya que no hay ningún cuerpo de solicitud para estos métodos.

Integrar una API

Integrar una API puede ser un proceso muy variado en función de la API. Por lo tanto, no hay un conjunto concreto de prácticas recomendadas que se puedan aplicar de forma genérica a todas las APIs. A continuación, se incluye una lista de consejos generales que pueden ayudarte a integrar una API.

  • Usa un envoltorio de API para las APIs que no sean RESTful.

    Si una API no es una API RESTful, puedes crear un envoltorio de API para exponer solo los métodos REST.

  • Si la API es casi RESTful, identifícala y actualízala.

    Si tu API es casi RESTful y solo tiene algunos comportamientos no REST, puedes actualizarla para resolverlos.

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

    Si tu API tiene valores generados por el servidor que son obligatorios para los métodos de la API, tendrás que configurar asignaciones de entrada para obtener el valor generado por el servidor y asignarlo a cada solicitud.

Siguientes pasos