Gérer les spécifications d'API

Cette page s'applique à Apigee et à Apigee hybrid.

Ce document explique comment gérer les spécifications d'API dans le hub d'API. Consultez également la page Présentation des spécifications d'API.

Ajouter une spécification d'API à une version

Vous pouvez ajouter une ou plusieurs spécifications d'API à une version d'API. Faites un choix parmi les options suivantes :

Ajouter une spécification lors de la création d'une version

À l'aide de l'interface utilisateur seule, vous pouvez ajouter une spécification d'API au moment où vous créez une version. Vous pouvez soit fournir l'URL d'une spécification à laquelle vous avez accès, soit importer un fichier de spécification directement depuis votre système.

Console

Pour ajouter une spécification à une nouvelle version, procédez comme suit :

  1. Pour commencer, suivez la procédure décrite dans la section Créer une version d'API. Lorsque vous atteignez la page Ajouter une nouvelle version, vous pouvez éventuellement ajouter un fichier de spécification à la version :
    1. Saisissez un nom à afficher pour le fichier de spécification. Vous pouvez utiliser n'importe quel nom.
    2. Sélectionnez le type de fichier de spécification. Le type de spécification est un attribut système configurable. Consultez également Attributs système.
    3. Fournissez un URI pointant vers un fichier de spécification d'API valide auquel vous avez accès, ou accédez à un fichier de spécifications d'API sur votre système.
    4. (Facultatif) Si vous souhaitez appliquer une validation stricte à la spécification importée, cochez la case Limiter l'importation de fichiers de spécification contenant des erreurs. Lorsque cette option est sélectionnée, une spécification contenant des erreurs de validation ne sera pas importée. Par défaut, les spécifications contenant des erreurs sont importées.
  2. Complétez les champs de la page Ajouter une nouvelle version, puis cliquez sur Créer lorsque vous avez terminé.

Ajouter une spécification à une version existante

Vous pouvez utiliser l'interface utilisateur ou l'API REST pour ajouter une spécification d'API à une version existante.

Console

Pour ajouter une spécification directement à une version, procédez comme suit:

  1. Dans la console Google Cloud, accédez à la page API Hub.

    Accéder au hub d'API
  2. Cliquez sur API.
  3. Recherchez l'API avec la version que vous souhaitez modifier. Utilisez l'option Filtrer pour spécifier des mots clés afin de filtrer la liste des API. Si besoin, utilisez l'option Rechercher pour trouver une API.
  4. Sélectionnez une API.
  5. Cliquez sur Ajouter un fichier de spécification.
  6. Saisissez un nom à afficher pour le fichier de spécification. Vous pouvez utiliser n'importe quel nom.
  7. Sélectionnez le type de fichier de spécification. Le type de spécification est un attribut système configurable. Consultez également Attributs système.
  8. Fournissez un URI pointant vers un fichier de spécification d'API valide auquel vous avez accès, ou accédez à un fichier de spécifications d'API sur votre système.
  9. (Facultatif) Si vous souhaitez appliquer une validation stricte à la spécification importée, cochez la case Limiter l'importation de fichiers de spécification contenant des erreurs. Lorsque cette option est sélectionnée, une spécification contenant des erreurs de validation ne sera pas importée. Par défaut, les spécifications contenant des erreurs sont importées.
  10. Sélectionnez la version à laquelle vous souhaitez ajouter le fichier de spécification.
  11. Cliquez sur Créer.

REST

Pour ajouter une spécification d'API à une version, utilisez l'API Ajouter une spécification d'API :

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  'https://apihub.googleapis.com/v1/projects/API_PROJECT/locations/API_LOCATION/apis/API_ID/versions/VERSION_ID/specs?spec_id=SPEC_ID' \
  -d "DATA_FILE or URI"

Remplacez les éléments suivants :

  • API_PROJECT : nom du projet hôte dans API Hub. Le projet hôte a été sélectionné lors du provisionnement d'API Hub.
  • API_LOCATION : emplacement du projet hôte. L'emplacement a été choisi lors du provisionnement d'API Hub.
  • API_ID: ID unique d'une ressource d'API.
  • VERSION_ID : ID d'une version associée à la ressource d'API.
  • SPEC_ID : (facultatif) identifiant de la spécification. S'il n'est pas fourni, un ID généré par le système sera utilisé. Le nom doit être une chaîne de 4 à 63 caractères, dont les caractères valides sont /[a-z][0-9]-/.
  • DATA_FILE or URI: fichier encodé en base64 contenant une spécification d'API valide ou un lien vers une spécification. Consultez l'exemple REST.

Exemple REST

Dans cet exemple, créez une nouvelle spécification dans le hub d'API avec une spécification OpenAPI encodée en base64. Lors de l'importation, le hub d'API analyse la spécification et crée une nouvelle entité de spécification incluant des métadonnées descriptives, ainsi que des ensembles d'entités d'opération et de définition. 

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d "@data.json" \
  https://apihub.googleapis.com/v1/projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs?spec_id=dstreetcarts-spec

Exemple de résultat :

{
    "name": "projects/common-dev-1/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec",
    "displayName": "Test Spec 1",
    "specType": {},
    "contents": {
      "contents": [Base64-encoded contents of an OpenAPI 3.0.2 file] },
    "details": {
      "description": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.\nYou can find out more about Swagger at [https://swagger.io](https://swagger.io).",
      "openApiSpecDetails": {
        "format": "OPEN_API_SPEC_3_0",
        "version": "1.0.11"
      }
    },
    "createTime": "2024-04-04T22:39:05.674986Z",
    "updateTime": "2024-04-04T22:39:05.674986Z"
  }

Pour renvoyer les détails de la spécification :

curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" \
  https://apihub.googleapis.com/v1/projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1

Résultat :

{
  "name": "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1",
  "displayName": "Test Version 3",
  "documentation": {},
  "specs": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec"
  ],
  "apiOperations": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/listpets",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/createpets",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/deletepet",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/getpetbyid",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/updatepet"
  ],
  "definitions": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/definitions/pet"
  ],
  "createTime": "2024-04-04T14:53:57.299213423Z",
  "updateTime": "2024-04-04T14:53:58.027321138Z"
}

Répertorier les spécifications

Cette section explique comment lister les spécifications associées à une version d'API.

Console

Pour lister les spécifications avec l'interface utilisateur, procédez comme suit :

  1. Dans la console Google Cloud, accédez à la page API Hub.

    Accéder au hub d'API
  2. Cliquez sur API.
  3. Utilisez l'option Filtrer pour spécifier des mots clés afin de filtrer la liste des API. Si besoin, utilisez l'option Rechercher pour trouver une API.
  4. Cliquez sur une API pour en afficher les détails.
  5. Dans l'onglet Versions, localisez la version que vous souhaitez inspecter.
  6. Sélectionnez une version.
  7. Toutes les spécifications liées à la version sont répertoriées dans la section Fichier de spécification.

REST

Pour lister les spécifications associées à une version d'API, utilisez l'API permettant de lister les spécifications :

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs"
      -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Remplacez les éléments suivants :

  • HUB_PROJECT : nom du projet hôte dans API Hub. Le projet hôte a été sélectionné lors du provisionnement du hub d'API.
  • HUB_LOCATION : emplacement du projet hôte. L'emplacement a été choisi lors du provisionnement du hub d'API.
  • API_ID: ID unique de la ressource d'API.
  • VERSION_ID: ID unique de la version.

Obtenir les détails d'une spécification

Cette section explique comment obtenir des détails sur une spécification d'API associée à une version.

Console

Pour afficher les détails d'une spécification à l'aide de l'interface utilisateur, procédez comme suit :

  1. Dans la console Google Cloud, accédez à la page API Hub.

    Accéder au hub d'API
  2. Cliquez sur API.
  3. Recherchez l'API avec la version contenant la spécification que vous souhaitez inspecter. Utilisez l'option Filtrer pour spécifier des mots clés afin de filtrer la liste des API. Si besoin, utilisez l'option Rechercher pour trouver une API.
  4. Cliquez sur une API pour en afficher les détails.
  5. Dans l'onglet Versions, localisez la version que vous souhaitez inspecter.
  6. Sélectionnez une version.
  7. Dans la section Fichier de spécification, sélectionnez une spécification pour afficher ses détails.

REST

Pour afficher les détails d'une spécification, utilisez l'API Obtenir les détails d'une spécification :

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Remplacez les éléments suivants :

  • HUB_PROJECT : nom du projet hôte dans API Hub. Le projet hôte a été sélectionné lors du provisionnement d'API Hub.
  • HUB_LOCATION : emplacement du projet hôte. L'emplacement a été choisi lors du provisionnement d'API Hub.
  • API_ID: ID unique de la ressource d'API.
  • VERSION_ID: ID unique de la version.
  • SPEC_ID: ID unique de la spécification.

Exemple de résultat :

{
  "name": "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec",
  "displayName": "Test Spec 1",
  "details": {
    "description": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.\nYou can find out more about Swagger at [https://swagger.io](https://swagger.io).",
    "openApiSpecDetails": {
      "format": "OPEN_API_SPEC_3_0",
      "version": "1.0.11"
    }
  },
  "createTime": "2024-04-04T22:39:05.098508600Z",
  "updateTime": "2024-04-04T22:39:06.661264958Z"
}

Supprimer une spécification d'API

Cette section explique comment supprimer une spécification d'API d'une version. La suppression d'une spécification entraîne également la suppression des opérations associées de la version.

Console

Pour supprimer des ressources d'API avec l'interface utilisateur :

  1. Dans la console Google Cloud, accédez à la page API Hub.

    Accéder au hub d'API
  2. Cliquez sur API.
  3. Localisez l'API associée à la version contenant la spécification que vous souhaitez supprimer. Utilisez l'option Filtrer pour spécifier des mots clés afin de filtrer la liste des API. Si besoin, utilisez l'option Rechercher pour trouver une API.
  4. Cliquez sur une API pour en afficher les détails.
  5. Dans l'onglet Versions, localisez la version contenant la spécification que vous souhaitez supprimer.
  6. Sélectionnez la version.
  7. Dans la section Fichier de spécification, sélectionnez Supprimer dans le menu Actions de la ligne de la spécification que vous souhaitez supprimer.
  8. Cliquez sur Supprimer.

REST

Pour supprimer une ressource d'API du hub d'API, utilisez l'API Supprimer une ressource d'API :

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X DELETE -H "Content-Type: application/json"

Remplacez les éléments suivants :

  • HUB_PROJECT : nom du projet hôte dans API Hub. Le projet hôte a été sélectionné lors du provisionnement du hub d'API.
  • HUB_LOCATION : emplacement du projet hôte. L'emplacement a été choisi lors du provisionnement du hub d'API.
  • API_ID: ID unique de la ressource d'API.
  • VERSION_ID: ID unique de la version.
  • SPEC_ID : ID unique de la spécification à supprimer.

Modifier les métadonnées d'une spécification

Vous pouvez modifier certaines des métadonnées associées à une spécification stockée dans le hub d'API. Pour obtenir la liste des métadonnées que vous pouvez modifier, consultez la section API de correctif de spécification.

Console

Vous pouvez modifier une spécification existante via la console Google Cloud. Par exemple, vous pouvez modifier le nom à afficher, importer un nouveau fichier de spécification, modifier le type de fichier et modifier les attributs :

  1. Dans la console Google Cloud, accédez à la page API Hub.

    Accéder au hub d'API
  2. Cliquez sur API.
  3. Localisez l'API associée à la version contenant la spécification que vous souhaitez supprimer. Utilisez l'option Filtrer pour spécifier des mots clés afin de filtrer la liste des API. Si besoin, utilisez l'option Rechercher pour trouver une API.
  4. Cliquez sur une API pour en afficher les détails.
  5. Dans l'onglet Versions, localisez la version contenant la spécification que vous souhaitez modifier.
  6. Sélectionnez la version.
  7. Sur la page "Versions", localisez la spécification que vous souhaitez modifier.
  8. Sélectionnez Modifier dans le menu Actions de la ligne de la spécification que vous souhaitez modifier.
  9. Dans le panneau de modification des spécifications, vous pouvez modifier l'une des métadonnées de spécification suivantes :
    • Nom à afficher
    • Type du fichier de spécification
    • Document de spécification : accédez au nouveau fichier de spécification à importer.
    • (Facultatif) Si vous souhaitez appliquer une validation stricte à la spécification importée, cochez la case Limiter l'importation de fichiers de spécification contenant des erreurs. Lorsque cette option est sélectionnée, une spécification contenant des erreurs de validation ne sera pas importée. Par défaut, les spécifications contenant des erreurs sont importées.
    • Attributs définis par l'utilisateur (le cas échéant)
  10. Cliquez sur Enregistrer.

REST

Pour modifier une spécification avec l'API REST :

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
    -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X PATCH -H "Content-Type: application/json"
    '{
      "display-name": DISPLAY_NAME.  # Use the request body to specify attribute changes
      "contents": {
         "contents": Base64-encoded string
         "mimeType": MIME_TYPE
      }
    }'

Remplacez les éléments suivants :

  • HUB_PROJECT : nom du projet hôte dans API Hub. Le projet hôte a été sélectionné lors du provisionnement du hub d'API.
  • HUB_LOCATION : emplacement du projet hôte. L'emplacement a été choisi lors du provisionnement du hub d'API.
  • API_ID: ID unique de la ressource d'API.
  • VERSION_ID: ID unique de la version.
  • SPEC_ID: ID unique de la spécification.
  • Corps de la requête : utilisez le corps de la requête pour spécifier les attributs à modifier. Consultez la section Définition des ressources d'une spécification.

Afficher les résultats de l'analyse lint de spécification

Le hub d'API fournit un outil lint (Spectral) intégré qui valide les spécifications OpenAPI de votre API. Consultez la section Valider les spécifications de l'API.

  1. Dans la console Google Cloud, accédez à la page API Hub.

    Accéder au hub d'API
  2. Cliquez sur API.
  3. Localisez l'API comportant la version contenant la spécification que vous souhaitez inspecter. Utilisez l'option Filtrer pour spécifier des mots clés afin de filtrer la liste des API. Si besoin, utilisez l'option Rechercher pour trouver une API.
  4. Cliquez sur une API pour en afficher les détails.
  5. Dans l'onglet Versions, localisez la version contenant la spécification que vous souhaitez inspecter.
  6. Cliquez sur Voir les résultats dans la colonne des résultats Lint pour afficher les résultats lint.

Obtenir le contenu d'une spécification

Cette fonctionnalité vous permet d'examiner le contenu d'une spécification importée dans le hub d'API.

Console

Pour afficher les détails d'une spécification à l'aide de l'interface utilisateur, procédez comme suit :

  1. Dans la console Google Cloud, accédez à la page API Hub.

    Accéder au hub d'API
  2. Cliquez sur API.
  3. Localisez l'API associée à la version contenant la spécification que vous souhaitez supprimer. Utilisez l'option Filtrer pour spécifier des mots clés afin de filtrer la liste des API. Si besoin, utilisez l'option Rechercher pour trouver une API.
  4. Cliquez sur une API pour en afficher les détails.
  5. Dans l'onglet Versions, localisez la version contenant la spécification que vous souhaitez inspecter.
  6. Cliquez sur le nom de la spécification pour afficher son contenu.

REST

L'API récupère le contenu brut encodé en base64 d'une spécification d'API importée dans le hub d'API. Utilisez l'API Get spécification content (Obtenir le contenu d'une spécification) :

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID:contents"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Remplacez les éléments suivants :

  • HUB_PROJECT : nom du projet hôte dans API Hub. Le projet hôte a été sélectionné lors du provisionnement d'API Hub.
  • HUB_LOCATION : emplacement du projet hôte. L'emplacement a été choisi lors du provisionnement d'API Hub.
  • API_ID: ID unique de la ressource d'API.
  • VERSION_ID: ID unique de la version.
  • SPEC_ID: ID unique de la spécification.

Exemple de résultat :

{
  "contents": "Base64-encoded file contents"
}