Gérer les ressources d'API

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

Enregistrer une API

Lorsque vous enregistrez une API auprès du hub d'API, vous créez et stockez une entité qui représente l'API. Nous appelons cette entité une ressource d'API. Les ressources d'API stockées dans le hub d'API sont incluses dans l'index de recherche, et fournissent des informations opérationnelles et descriptives détaillées sur l'API. Lors de l'enregistrement d'une API, ou suite à cet enregistrement, vous pouvez ajouter et modifier les attributs de la ressource d'API afin de constituer une description détaillée de l'API.

Console

Pour enregistrer une API, procédez comme suit :

  1. Dans la console Google Cloud, accédez à la page API du hub d'API.

    Accéder au hub d'API
  2. Cliquez sur Enregistrer l'API.

  3. Sous Informations générales, vous pouvez éventuellement spécifier un ID unique pour l'API. Si vous ne fournissez pas d'ID, le système en génère un pour vous. Si vous souhaitez saisir un identifiant, cliquez sur Spécifier un identifiant unique.

    Le nom doit comporter entre 4 et 500 caractères, et les caractères valides sont /[A-Z][a-z][0-9]-/.. L'ID est le dernier composant du nom de ressource d'API unique, complet, au format suivant : projects/PROJECT/locations/LOCATION/apis/API_ID

  4. (Obligatoire) Indiquez un nom à afficher pour la ressource d'API.
  5. Si vous le souhaitez, vous pouvez ajouter des attributs supplémentaires décrivant l'API. Vous pouvez revenir à l'API à tout moment pour ajouter ou modifier des attributs d'API. Consultez la section Modifier une ressource d'API.
    • Informations sur le propriétaire (facultatif) : nom et adresse e-mail du propriétaire de l'API.
    • Informations supplémentaires (facultatif) : spécifiez des attributs pour définir votre API et la rendre plus facile à rechercher. Vous pouvez définir les valeurs par défaut pour certains de ces attributs dans les paramètres. Pour en savoir plus, consultez la section Gérer les attributs.
    • Attributs définis par l'utilisateur (facultatif) : il s'agit des attributs que vous définissez dans les paramètres. Pour en savoir plus, consultez la section Gérer les attributs.
  6. Cliquez sur S'inscrire.

REST

Pour enregistrer une API, utilisez l'API REST Créer une API.

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -d '{
    "display_name": "DISPLAY_NAME",            # Required attribute
    "description": "DESCRIPTION"               # description is an optional attribute
    }
    'https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis?api_id=API_ID

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 (facultatif) : saisissez un ID unique pour l'API. Si vous ne fournissez pas ce paramètre de requête, le système génère un ID unique pour vous. Le nom doit comporter entre 4 et 500 caractères, et les caractères valides sont /[A-Z][a-z][0-9]-/.. Le nom est le dernier composant du nom de ressource d'API unique, complet, au format suivant : projects/PROJECT/locations/LOCATION/apis/API_ID
  • DISPLAY_NAME (obligatoire) : nom à afficher de la ressource d'API. Vous pouvez utiliser n'importe quel nom.
  • DESCRIPTION (facultatif) : vous pouvez ajouter un certain nombre d'attributs facultatifs pour décrire la ressource d'API, y compris une description, un propriétaire, un lien vers la documentation de l'API, etc. Ces attributs facultatifs sont répertoriés et décrits dans la définition des ressources d'API.

Répertorier les ressources d'API

Cette section explique comment lister les ressources d'API dans le hub d'API. En ajoutant un filtre, vous pouvez limiter les API renvoyées dans la réponse.

Console

Pour lister les ressources d'API, procédez comme suit :

  1. Dans la console Google Cloud, accédez à la page API du hub d'API.

    Accéder au hub d'API

    La liste de toutes les API ajoutées au hub d'API apparaît sur la page d'accueil des API.

  2. 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.

REST

Pour répertorier toutes les ressources d'API de votre projet de hub d'API, utilisez l'API Lister les API :

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis"
  -X GET -H "Authorization: Bearer: $(gcloud auth print-access-token)" -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.

Exemple de résultat :

{
  "apis": [
    {
      "name": "projects/myproject/locations/us-central1/apis/a035eb3b-658e-467a-89d3-9cca2bbacd32-2",
      "displayName": "TestApi2",
      "documentation": {}
    },
    {
      "name": "projects/myproject/locations/us-central1/apis/a035eb3b-658e-467a-89d3-9cca2bbacd32-1",
      "displayName": "TestApi1",
      "documentation": {}
    },
    {
      "name": "projects/myproject/locations/us-central1/apis/foo9013cfev",
      "displayName": "sample",
      "documentation": {}
    },
    {
      "name": "projects/myproject/locations/us-central1/apis/foo90121",
      "displayName": "sample",
      "documentation": {}
    },
    ...
    ],
    "nextPageToken": "f4f4d78b-a974-46db-a214-dc139f8e9c8a"
  }

Exemple REST avec filtre

Vous pouvez filtrer les résultats de la liste à l'aide de l'API. Dans cet exemple, nous filtrons les API selon un attribut défini par le système : 

curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  'https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis' \
  -d filter="owner.email=\"testowner3@gmail.com\"" -d page_size=10

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.

Exemple de résultat, filtré par propriétaire :

{
  "apis": [
    {
      "name": "projects/myproject/locations/us-central1/apis/theme-park-management-api",
      "displayName": "Theme Park Management API",
      "documentation": {}
    },
    {
      "name": "projects/myproject/locations/us-central1/apis/restaurant-api",
      "displayName": "Restaurant API",
      "documentation": {}
    },
    {
      "name": "projects/myproject/locations/us-central1/apis/casino-management-api",
      "displayName": "Casino Management API",
      "documentation": {}
    },
    {
      "name": "projects/myproject/locations/us-central1/apis/hotel-boooking-api",
      "displayName": "Hotel Booking API",
      "documentation": {}
    },
    {
      "name": "projects/myproject/locations/us-central1/apis/test-march-26-api3",
      "displayName": "Test Pets API",
      "documentation": {}
    },
    {
      "name": "projects/myproject/locations/us-central1/apis/test-march-26-api2",
      "displayName": "Test Pets API",
      "documentation": {}
    },
    {
      "name": "projects/myproject/locations/us-central1/apis/test-march-26-api1",
      "displayName": "Test Pets API",
      "documentation": {}
    }
  ]
}

Obtenir des détails sur une ressource d'API

Cette section explique comment obtenir des informations détaillées sur une ressource d'API.

Console

Pour afficher les détails d'une ressource d'API, procédez comme suit :

  1. Dans la console Google Cloud, accédez à la page API du hub d'API.

    Accéder au hub d'API
  2. 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.
  3. Cliquez sur une API pour afficher sa page d'informations détaillées.

REST

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

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_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.

Exemple de résultat :

{
  "name": "projects/myproject/locations/us-central1/apis/myapi",
  "displayName": "My Test API",
  "description": "This is a test API.",
  "documentation": {},
  "owner": {
    "displayName": "Test API,
    "email": "testowner@gmail.com"
  },
  "versions": [
    "projects/myproject/locations/us-central1/apis/myapi/versions/myapi-version1"
  ],
  "createTime": "2024-03-26T10:13:15.668867002Z",
  "updateTime": "2024-03-26T10:13:16.700716401Z"
}

Supprimer une ressource d'API

Cette section explique comment supprimer une ressource d'API.

Console

Lorsque vous supprimez une API dans l'interface utilisateur, toutes les versions sous-jacentes de l'API et les spécifications d'API associées (le cas échéant) sont supprimées.

Pour supprimer une ressource d'API :

  1. Dans la console Google Cloud, accédez à la page API du hub d'API.

    Accéder au hub d'API
  2. Utilisez l'option Filtrer pour spécifier des mots clés afin de filtrer la liste des API. Si nécessaire, utilisez la recherche pour localiser l'API à supprimer.
  3. Dans le menu Actions (à droite de la ligne contenant l'API), cliquez sur Supprimer.

REST

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

Par défaut, une API ne peut être supprimée que si toutes les versions sous-jacentes sont supprimées. Si vous souhaitez supprimer toutes les versions d'une API en une seule étape, définissez le paramètre de requête force sur true dans l'API REST de suppression.

curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  'https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID'

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 à supprimer.

Pour supprimer l'API et toutes les versions sous-jacentes, définissez le paramètre de requête force sur true. Par exemple :

curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  'https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID?force=true'

Modifier une ressource d'API

Cette section explique comment modifier une ressource d'API. Tous les attributs de ressources d'API ne sont pas modifiables. Pour obtenir la liste des champs modifiables, consultez la documentation de référence de l'API Patch.

Console

Pour modifier une API, procédez comme suit :

  1. Dans la console Google Cloud, accédez à la page API du hub d'API.

    Accéder au hub d'API
  2. Utilisez l'option Filtrer pour spécifier des mots clés afin de filtrer la liste des API. Si nécessaire, utilisez la recherche pour trouver une API à modifier.
  3. Cliquez sur une API pour afficher sa page d'informations détaillées.
  4. Cliquez sur Modifier l'API.
  5. Sur la page Modifier l'API, apportez vos modifications. Cliquez sur Continuer pour passer à l'ensemble d'attributs modifiables suivant.
    • Informations générales : vous pouvez modifier le nom à afficher de l'API.
    • Informations sur le propriétaire : nom et adresse e-mail du propriétaire de l'API.
    • Informations supplémentaires (facultatif) : il s'agit des attributs définis par le système. Vous pouvez spécifier des valeurs par défaut personnalisées pour ces attributs dans Gérer les attributs.
    • Attributs définis par l'utilisateur : il s'agit des attributs personnalisés définis par l'utilisateur. Vous pouvez spécifier des attributs personnalisés dans Gérer les attributs.
  6. Cliquez sur Enregistrer.

REST

Pour mettre à jour une ressource d'API, utilisez l'API de ressource d'API Patch.

curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -d '{
          "display_name": "Updated Test Docs API",        # Example request body with changes
          "description": "This is the updated test API.",
          "owner": {
            "display_name": "Updated Docs Owner",
            "email": "updateddocsowner@gmail.com"
            }
          }
          ' https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID

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 l'API à mettre à jour.
  • Corps de la requête : utilisez le corps de la requête pour spécifier les attributs que vous souhaitez modifier. Consultez la description du corps de la requête d'API.