Exigences de l'API pour l'intégration d'une API

Ce document décrit les exigences générales des API qui peuvent être intégrées en tant que fournisseur de types à Deployment Manager. Utilisez ces instructions pour comprendre les caractéristiques d'une API attendue par Deployment Manager. Si votre API ne correspond pas exactement aux spécifications décrites ici, vous pourrez peut-être résoudre ces incohérences à l'aide d'options d'API avancées.

L'API possède un document descripteur valide

Un document descripteur décrit une API et ses ressources. Seules les API reposant sur une spécification OpenAPI ou un document descripteur Google Discovery peuvent être intégrées à Deployment Manager. Pour obtenir des informations complètes sur la création d'une spécification OpenAPI, accédez au dépôt OpenAPI GitHub.

Le point de terminaison du document descripteur de l'API est accessible

Deployment Manager envoie une requête HTTP pour obtenir le document descripteur de l'API. Veillez donc à héberger votre document descripteur dans un emplacement accessible par Deployment Manager. Il peut s'agir d'une URL disponible publiquement ou d'un point de terminaison protégé par des paramètres d'authentification de base.

L'API accepte l'authentification de base ou OAuth2 si elle est hébergée sur certains services Google

Deployment Manager gère actuellement l'authentification de base (nom d'utilisateur et mot de passe) et l'authentification OAuth 2.0 pour certaines API hébergées sur Google Kubernetes Engine ou sur Google Endpoints. Vous pouvez configurer l'authentification afin d'utiliser le compte de service du projet.

Pour en savoir plus, consultez la page Créer un fournisseur de types.

Les opérations CRUD (création, lecture, mise à jour et suppression) sont acceptées

L'API en question doit être une API RESTful compatible avec les opérations CRUD. Ces opérations sont les suivantes :

  • Opérations de création : permettent de créer des ressources. Une requête HTTP POST doit être effectuée.
  • Opérations de lecture : permettent d'obtenir des informations sur les ressources de l'API. Une requête HTTP GET doit être effectuée.
  • Opérations de mise à jour : permettent de mettre à jour une ressource. Une requête HTTP PUT doit être effectuée.
  • Opérations de suppression : permettent de supprimer des ressources. Une requête HTTP DELETE doit être effectuée.

Une API compatible uniquement avec des opérations CRUD partielles fonctionnera, mais se comportera différemment en fonction des opérations disponibles.

Compatibilité avec les requêtes GET Compatibilité avec les requêtes CREATE Compatibilité avec les requêtes UPDATE Compatibilité avec les requêtes DELETE Comportement spécifique de l'API ?
Oui Oui Oui Oui Aucun
Oui Oui Oui Non Les utilisateurs peuvent abandonner une ressource, mais ne peuvent pas la supprimer.
Oui Oui Non Oui Toute modification apportée à une ressource existante échoue. Les utilisateurs doivent supprimer et recréer une ressource pour la mettre à jour.
Oui Oui Non Non Les deux comportements décrits ci-dessus.
Oui Non Oui Oui Si une API n'accepte pas les requêtes de création, les utilisateurs peuvent ajouter des ressources existantes au déploiement en mettant à jour le déploiement avec la règle ACQUIRE.
Oui Non Oui Non Les utilisateurs peuvent acquérir une ressource ou la mettre à jour après l'avoir acquise, mais ne peuvent pas la supprimer.
Oui Non Non Oui Les utilisateurs peuvent supprimer une ressource et en obtenir une, ou en ajouter une existante à un déploiement.
Oui Non Non Non Les utilisateurs peuvent acquérir une ressource existante ou la supprimer avec la règle ABANDON.

Tous les paramètres de chemins et de requêtes sont résolus

Tous les paramètres de chemins et de requêtes de l'API doivent exister dans le corps de la ressource ou dans toutes les méthodes de l'API afin que Deployment Manager puisse les faire correspondre lorsqu'un utilisateur les fournit. Les conditions suivantes s'appliquent aux paramètres de chemins et de requêtes.

Les paramètres de chemins/requêtes dans la méthode POST doivent également figurer dans la méthode PUT

La déclaration suivante n'est pas valide, car myParameter est défini dans la méthode POST, mais pas dans la méthode PUT :

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

Chaque paramètre des méthodes autres que POST doit figurer soit dans toutes les interfaces de méthodes, soit au sein de la ressource, avec des considérations spéciales si le paramètre est généré par le serveur.

Dans le meilleur des cas, l'API peut ressembler aux exemples suivants dans lesquels le paramètre name apparaît pour toutes les méthodes.

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

Dans un autre scénario, un champ peut apparaître comme un paramètre de chemin pour une méthode, mais pas pour d'autres. Dans ce cas, le champ doit faire partie de la ressource de l'API. Exemple :

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

Dans cet exemple, l'hypothèse est que id est une valeur générée par le serveur qui est présente sur la ressource, mais pas lors de la création d'une requête POST. Si la propriété id est requise pour effectuer une requête sur une ressource existante, mais que la propriété n'est pas présente sur la ressource ni disponible dans le chemin, cela cause des problèmes lors du portage de l'API vers Deployment Manager.

Le comportement subtil de l'API nécessite une configuration supplémentaire

Certains comportements de l'API nécessitent une configuration supplémentaire pour l'intégration à Deployment Manager. Ces comportements incluent les suivants :

  • Valeurs générées par le serveur : certaines ressources de l'API ont des propriétés générées par le serveur qui changent après chaque requête ou lorsqu'un événement spécifique se produit dans l'API. Vous pouvez utiliser les options d'API avancées pour indiquer à Deployment Manager d'obtenir cette nouvelle valeur chaque fois qu'une requête est envoyée.

    Par exemple, une API peut nécessiter la dernière propriété d'empreinte d'une ressource avant d'autoriser une requête de mise à jour. Utilisez les options d'API avancées pour indiquer à Deployment Manager d'obtenir cette valeur chaque fois que l'utilisateur effectue une requête de mise à jour du déploiement.

  • Gestion des saisies utilisateur : par exemple, si votre API exige que la valeur d'un champ soit toujours précédée par un ID de projet, vous pouvez utiliser des mappages d'entrée pour ajouter automatiquement cette information au lieu d'obliger vos utilisateurs à le faire manuellement.

  • Valeurs de champ différentes pour chaque méthode : pour les méthodes qui réutilisent le même champ avec des valeurs différentes, vous pouvez utiliser les options de l'API pour indiquer à Deployment Manager quand utiliser quelle valeur.

Pour en savoir plus, consultez la page Définir des options d'API avancées.

Étapes suivantes