Bonnes pratiques pour l'ajout d'un fournisseur de types

Cette page décrit les bonnes pratiques relatives à la création d'une API à ajouter à Deployment Manager en tant que fournisseur de types et à l'ajout d'une API existante en tant que fournisseur de types.

Deployment Manager vous permet d'ajouter des API en tant que fournisseurs de types afin d'exposer leurs ressources comme types que vous pouvez appeler lors de la configuration. Pour faciliter cette procédure, suivez ces bonnes pratiques lors de la configuration ou de la création d'une API.

Créer une API

Si vous créez une API à intégrer à Deployment Manager, suivez les bonnes pratiques ci-dessous.

Utiliser des méthodes CRUD standards (création, lecture, mise à jour et suppression) et éviter les méthodes personnalisées

Évitez de créer des méthodes personnalisées si possible. Utilisez les méthodes REST standards, telles que GET, POST, PUT et DELETE. Ces méthodes sont reconnues par Deployment Manager et peuvent être automatiquement mappées.

Pour les API Discovery, vous devez nommer vos méthodes d'API conformément au mappage suivant :

Méthode REST Nom recommandé pour les méthodes d'API
POST create ou insert
GET get
PUT update
DELETE delete

Pour les spécifications OpenAPI, vous ne pouvez pas nommer les méthodes d'API différemment des méthodes REST standards.

Utiliser des chemins de ressources prévisibles

Pour les spécifications OpenAPI, Deployment Manager accepte deux techniques pour identifier une interface RESTful. La première doit être utilisée si toutes les méthodes REST pour une ressource appartiennent au même chemin de ressource :

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

Si vous devez séparer les méthodes, indiquez le même chemin de ressource. L'exemple suivant est valide, car il fait référence à la même ressource /foo :

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

En revanche, l'exemple suivant est incorrect, car il fait référence à deux ressources différentes pour Deployment Manager :

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

Dans de rares cas, vous pouvez être tenté de nommer vos chemins de ressources comme suit :

foo/create
  post:

foo/delete
  delete:

Ces chemins ne sont pas valides, car Deployment Manager ne peut pas identifier l'interface RESTful.

Utiliser des valeurs cohérentes dans l'interface

Indiquez les mêmes entrées et noms de chemins dans les méthodes POST et PUT. Cette bonne pratique s'applique également aux valeurs des paramètres. En d'autres termes, la syntaxe des valeurs de paramètres doit être la même pour toutes les méthodes.

Par exemple, si vous nommez un paramètre email dans le corps d'une requête POST, n'intitulez pas le même paramètre emailAddress dans la requête PUT.

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

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

Si vous devez utiliser ce type de comportement, indiquez à Deployment Manager comment le gérer en définissant des options d'API avancées.

Il est également nécessaire de garder le même corps de requête pour les méthodes POST et PUT. Pour les méthodes GET et DELETE, seul le chemin est applicable, car ces dernières ne disposent normalement pas de corps de requête.

Intégrer une API existante

La procédure d'intégration d'une API existante varie selon l'API. Par conséquent, il n'existe aucun ensemble concret de bonnes pratiques qui peuvent être appliquées de manière générique à toutes les API. Vous trouverez ci-dessous une liste de conseils généraux qui vous aideront à intégrer une API existante.

  • Utilisez un wrapper d'API pour les API non RESTful.

    Si l'API à intégrer n'est pas une API RESTful, vous pouvez créer un wrapper d'API pour exposer uniquement les méthodes REST.

  • Si l'API est presque RESTful, identifiez et mettez à jour l'API.

    Si l'API est presque RESTful et ne comprend que quelques comportements non-REST, vous pouvez mettre à jour l'API pour résoudre ces comportements.

  • Les valeurs générées par le serveur nécessitent toujours un mappage d'entrée.

    Si votre API dispose de valeurs générées par le serveur requises par ses méthodes, vous devez configurer des mappages d'entrée pour obtenir la valeur générée par le serveur et la mapper pour chaque requête.

Étapes suivantes