Publier des API

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

Consultez la documentation d'Apigee Edge.

Publiez des API sur votre portail pour les mettre à la disposition des développeurs d'applications, comme décrit dans les sections suivantes.

Présentation de la publication d'API

Le processus de publication des API sur votre portail comporte deux étapes :

  1. Sélectionnez le produit d'API que vous souhaitez publier sur votre portail.
  2. Affichez la documentation de référence de l'API à partir de votre document OpenAPI ou de votre schéma GraphQL afin de permettre aux développeurs d'applications d'en savoir plus sur vos API. (Pour plus d'informations, consultez la page À propos de la documentation de l'API.)

Qu'est-ce qui est publié sur le portail ?

Lorsque vous publiez une API, les mises à jour suivantes sont apportées automatiquement à votre portail :

  • Documentation de référence sur les API L'interface fournie varie selon que vous publiez votre API à l'aide d'un document OpenAPI ou d'un schéma GraphQL. Consultez :
  • Un lien vers la page de référence de l'API a été ajouté à la page des API.

    La page des API (incluse dans l'exemple de portail) fournit une liste de toutes les API publiées sur votre portail, classées par ordre alphabétique, ainsi que des liens vers la documentation de référence de l'API correspondante pour plus d'informations. Vous pouvez éventuellement personnaliser les éléments suivants :

    • Image affichée pour chaque fiche d'API
    • Catégories utilisées pour taguer des API afin de permettre aux développeurs d'identifier des API associées sur la page des API
    Page des API du portail en ligne présentant deux catégories et l'utilisation des images Page des API du portail en ligne présentant deux catégories et l'utilisation des images

SmartDocs (OpenAPI)

Lorsque vous publiez une API à l'aide d'un document OpenAPI, la documentation de référence de l'API SmartDocs est ajoutée à votre portail.

Les développeurs peuvent consulter la documentation de référence SmartDocs de votre API et utiliser le panneau Essayer cette API pour créer une requête API et afficher le résultat. Essayez cette API avec des points de terminaison non sécurisés ou des points de terminaison sécurisés à l'aide de l'authentification de base, de clé API ou OAuth, en fonction de la méthode de sécurité définie dans votre document OpenAPI. Pour OAuth, les flux suivants sont compatibles : code d'autorisation, mot de passe et identifiants client.

Page de documentation de référence de l'API contenant des accroches indiquant comment autoriser votre appel d'API, retirer le panneau "Essayer cette API", télécharger la spécification appropriée et exécuter l'API.

Page de documentation de référence de l'API contenant des accroches indiquant comment autoriser votre appel d'API, retirer le panneau "Essayer cette API", télécharger la spécification appropriée et exécuter l'API.

Cliquez sur Plein écran pour développer le panneau "Essayer cette API". Le panneau développé vous permet d'afficher les exemples de code et d'appel curl dans différents formats tels que HTTP, Python, Node.js et d'autres, comme indiqué ci-dessous.

Panneau "Essayer cette API" développé

Panneau "Essayer cette API" développé

GraphQL Explorer

Lorsque vous publiez une API à l'aide d'un schéma GraphQL, GraphQL Explorer est ajouté à votre portail. GraphQL Explorer est un playground interactif permettant d'exécuter des requêtes sur votre API. L'explorateur est basé sur GraphiQL, une implémentation de référence de l'IDE GraphQL développé par la GraphQL Foundation.

Les développeurs peuvent utiliser GraphQL Explorer pour explorer la documentation interactive basée sur un schéma, créer et exécuter des requêtes, afficher les résultats des requêtes et télécharger le schéma. Pour sécuriser l'accès à votre API, les développeurs peuvent transmettre des en-têtes d'autorisation dans le volet En-têtes de requêtes. Pour en savoir plus sur GraphQL, consultez la page graphql.org.

GraphQL Explorer sur le portail

GraphQL Explorer sur le portail

À propos de la documentation de l'API

Chaque document OpenAPI ou GraphQL sert de source d'information tout au long du cycle de vie d'une API. Le même document est utilisée à chaque phase du cycle de vie de l'API, du développement à la publication, en passant par la surveillance. Lorsque vous modifiez un document, vous devez être conscient de l'impact des modifications de votre API sur les autres phases du cycle de vie, comme décrit dans la section Que se passe-t-il si je modifie un document ?

Lorsque vous publiez votre API sur un portail, vous enregistrez une version du document OpenAPI ou GraphQL pour afficher la documentation de référence de l'API. Si vous modifiez le document, vous pouvez décider de mettre à jour la documentation de référence de l'API publiée sur le portail afin de refléter les dernières modifications.

À propos des URL de rappel

Si vos applications nécessitent une URL de rappel, par exemple lorsque vous utilisez le type d'attribution de code d'autorisation OAuth 2.0 (souvent appelé autorisation OAuth à trois acteurs), vous pouvez demander aux développeurs de spécifier une URL de rappel lorsqu'ils enregistrent leurs applications. L'URL de rappel spécifie généralement l'URL d'une application désignée pour recevoir un code d'autorisation au nom de l'application cliente. Pour plus d'informations, consultez la section Mettre en œuvre le type d'attribution du code d'autorisation.

Vous pouvez choisir d'exiger ou non une URL de rappel lors de l'enregistrement de l'application lorsque vous ajoutez une API à votre portail. Vous pouvez modifier ce paramètre à tout moment, comme décrit dans la section Gérer l'URL de rappel d'une API.

Lors de l'enregistrement d'une application, les développeurs doivent entrer une URL de rappel pour toutes les API qui en ont besoin, comme décrit dans la section Enregistrer des applications.

Configurer le proxy d'API pour qu'il soit compatible avec le panneau "Essayer cette API"

Avant de publier vos API à l'aide d'un document OpenAPI, vous devez configurer votre proxy d'API pour effectuer des requêtes dans le panneau "Essayer cette API" de la documentation de référence de l'API SmartDocs, comme suit :

  • Ajoutez la compatibilité CORS à vos proxys d'API pour appliquer des requêtes d'origine croisée côté client.
    CORS est un mécanisme standard qui permet aux appels XMLHttpRequest (XHR) JavaScript exécutés sur une page Web d'interagir avec les ressources de domaines extérieures au domaine d'origine. CORS est une solution couramment mise en œuvre en réponse à la règle de même origine appliquée par tous les navigateurs.
  • Mettez à jour la configuration de votre proxy d'API si vous utilisez l'authentification de base ou OAuth 2.0.

Le tableau suivant récapitule les exigences de configuration des proxys d'API pour être compatible avec le panneau "Essayer cette API" dans la documentation de référence de l'API SmartDocs, en fonction de l'accès de l'authentification.

Accès de l'authentification Exigences de configuration des règles
Aucune ou clé API Pour ajouter la compatibilité avec le CORS à votre proxy d'API, suivez les étapes décrites dans la section Ajouter la compatibilité CORS à un proxy d'API.
Authentification de base Procédez comme suit :
  1. Pour ajouter la compatibilité avec le CORS à votre proxy d'API, suivez les étapes décrites dans la section Ajouter la compatibilité CORS à un proxy d'API.
  2. Dans la règle "Add CORS", vérifiez que l'en-tête Access-Control-Allow-Headers inclut l'attribut authorization. Exemple : 
    <Header name="Access-Control-Allow-Headers">
  origin, x-requested-with, accept, content-type, authorization
</Header>
OAuth 2.0
  1. Pour ajouter la compatibilité avec le CORS à votre proxy d'API, suivez les étapes décrites dans la section Ajouter la compatibilité CORS à un proxy d'API.
  2. Dans la règle "Add CORS", vérifiez que l'en-tête Access-Control-Allow-Headers inclut l'attribut authorization. Exemple : 
    <Header name="Access-Control-Allow-Headers">
  origin, x-requested-with, accept, content-type, authorization
</Header>
  3. Corrigez le comportement non conforme à la norme RFC dans votre règle OAuth 2.0. Pour plus de commodité, utilisez l'exemple de solution OAuth 2.0 fourni sur GitHub ou procédez comme suit :
    • Assurez-vous que l'élément <GrantType> de la règle OAuth 2.0 est défini sur request.formparam.grant_type (paramètre de formulaire). Pour en savoir plus, consultez la section <GrantType>.
    • Assurez-vous que la valeur token_type dans la règle OAuth 2.0 est définie sur Bearer et non sur la valeur par défaut BearerToken.

Gérer des API

Gérez vos API comme décrit dans les sections suivantes.

Découvrir les API

Utilisez la console ou la commande curl pour afficher les API qui se trouvent dans votre portail.

Console

Pour afficher le catalogue d'API :

  1. Sélectionnez Publier > Portails et sélectionnez votre portail.

  2. Cliquez sur Catalogue d'API sur la page d'accueil du portail.
    Vous pouvez également sélectionner Catalogue d'API dans le menu déroulant du portail dans la barre de navigation supérieure.
    L'onglet API du catalogue des API affiche la liste des API ajoutées à votre portail.

    Onglet &quot;API&quot; présentant des informations sur les API telles que le nom, la description, la visibilité, les catégories, les spécifications associées et l&#39;heure de modification

    Onglet &quot;API&quot; présentant des informations sur les API telles que le nom, la description, la visibilité, les catégories, les spécifications associées et l&#39;heure de modification

    Comme le montre la figure précédente, l'onglet API vous permet d'effectuer les opérations suivantes :

curl

Pour répertorier les API à l'aide de organizations.sites.apidocs/list :

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Remplacez les éléments suivants :

  • ORG_NAME par le nom de l'organisation. Par exemple, my-org.
  • SITE_ID par le nom du portail, au format ORG_NAME-PORTAL_NAME, où ORG_NAME est le nom de l'organisation et PORTAL_NAME le nom du portail converti en minuscules sans espaces ni tirets. Par exemple, my-org-myportal.

Consultez les notes de pagination pour obtenir des instructions sur l'utilisation de la pagination dans la charge utile de réponse.

Charge utile de la réponse :

{
  "status": "success",
  "message": "one page of apidocs returned",
  "requestId": "1167960478",
  "data": [
    {
      "siteId": "my-org-myportal",
      "title": "Hello New World",
      "description": "Simple hello new world example",
      "specId": "hellowworld",
      "modified": "1695841621000",
      "anonAllowed": true,
      "imageUrl": "/files/camper1.jpg?v=1695841491415",
      "id": "381054",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello New World"
    },
    {
      "siteId": "my-org-myportal",
      "title": "mock-product",
      "description": "Mock product",
      "specId": "apigee spec",
      "modified": "1698956849000",
      "anonAllowed": true,
      "id": "399638",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
      ],
      "published": true,
      "apiProductName": "mock-product"
    },
    {
      "siteId": "my-org-myportal",
      "title": "Hello World 2",
      "description": "Simple hello world example",
      "specId": "hello-new-world",
      "modified": "1698950207000",
      "anonAllowed": true,
      "imageUrl": "/files/book-tree.jpg?v=1698165437881",
      "id": "399668",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello World 2"
    }
  ],
  "nextPageToken": ""
}

Où :

  • modified: Heure de la dernière modification de l'article de catalogue en millisecondes depuis l'epoch. Par exemple, 1698165480000.
  • id: ID de l'article de catalogue. Par exemple, 399668.

Notes de pagination :

  • Taille de page : Utilisez pageSize pour spécifier le nombre d'éléments de liste à renvoyer sur une page. La valeur par défaut est 25 et la valeur maximale est 100. S'il existe d'autres pages, le champ nextPageToken est renseigné avec un jeton :

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE" \
   -H "Authorization: Bearer $(gcloud auth print-access-token)"

    Remplacez :

    • PAGE_SIZE par le nombre d'éléments de liste à renvoyer sur une page. Par exemple, 10.

    Charge utile de la réponse :

    {
  "status": "success",
  "message": "one page of apidocs returned",
  "requestId": "918815495",
  "data": [
    {
      "siteId": "my-org-myportal",
      "title": "Hello New World",
      "description": "Simple hello new world example",
      "specId": "apigee",
      "modified": "1699146887000",
      "anonAllowed": true,
      "imageUrl": "/files/camper1.jpg?v=1695841491415",
      "id": "381054",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello New World"
    }
  ],
  "nextPageToken": "7zcqrin9l6xhi4nbrb9"
}

  • Jeton de page :

    Utilisez pageToken pour récupérer les pages suivantes lorsqu'il en existe plusieurs :

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN" \
      -H "Authorization: Bearer $(gcloud auth print-access-token)"

    Remplacez :

    • PAGE_SIZE par le nombre d'éléments de liste à renvoyer sur une page. Par exemple, 10.
    • PAGE_TOKEN avec la valeur nextPageToken. Exemple : 7zcqrin9l6xhi4nbrb9.

Ajouter une API

Pour ajouter une API à votre portail :

Console

  1. Accédez au catalogue d'API.
  2. Cliquez sur l'onglet API, s'il n'est pas déjà sélectionné.

  3. Cliquez sur Ajouter.

    La boîte de dialogue Ajouter un produit d'API au catalogue s'affiche.

  4. Sélectionnez le produit d'API que vous souhaitez ajouter à votre portail.

  5. Cliquez sur Suivant. La page Détails de l'API s'affiche.

  6. Configurez le contenu de la documentation de référence de l'API et sa visibilité sur le portail :

    Champ Description
    Publiée Sélectionnez Publiée pour publier l'API sur votre portail. Décochez la case si vous n'êtes pas prêt à publier l'API. Vous pouvez modifier le paramètre ultérieurement, comme décrit dans la section Publier ou annuler la publication d'une API.
    Titre à afficher Mettez à jour le titre de votre API affiché dans le catalogue. Par défaut, le nom de produit d'API est utilisé. Vous pouvez modifier l'intitulé ultérieurement, comme décrit dans l'article Modifier l'intitulé et la description.
    Description Mettez à jour la description de l'API affichée dans le catalogue. Par défaut, la description du produit d'API est utilisée. Vous pouvez modifier la description ultérieurement, comme décrit dans l'article Modifier l'intitulé et la description.
    Exiger des développeurs qu'ils spécifient une URL de rappel Activez cette option si vous souhaitez exiger des développeurs d'applications qu'ils spécifient une URL de rappel. Vous pourrez ajouter ou mettre à jour l'URL de rappel ultérieurement, comme décrit dans la section Gérer l'URL de rappel d'une API.
    Documentation de l'API

    Pour utiliser un document OpenAPI :

    1. Sélectionnez OpenAPI document (Document OpenAPI).
    2. Cliquez sur Select Document (Sélectionner un document).
    3. Effectuez l'une des opérations suivantes :
      • Cliquez sur l'onglet Importer un fichier, puis importez un fichier.
      • Cliquez sur l'onglet Importer depuis une URL et importez une spécification en indiquant un nom et une URL à partir desquels effectuer l'importation.
    4. Cliquez sur Sélectionner.

    Pour utiliser un schéma GraphQL :

    1. Sélectionnez Schéma GraphQL.
    2. Cliquez sur Select Document (Sélectionner un document).
    3. Accédez au schéma GraphQL et sélectionnez-le.
    4. Cliquez sur Sélectionner.

    Vous pouvez également sélectionner Aucune documentation et en ajouter une après l'ajout de l'API, comme décrit dans la page Gérer la documentation de l'API.

    Visibilité

    Si vous n'êtes pas inscrit au programme bêta de la fonctionnalité de gestion des audiences, sélectionnez l'une des options suivantes :

    • Utilisateurs anonymes pour autoriser tous les utilisateurs à afficher l'API.
    • Utilisateurs enregistrés pour autoriser uniquement les utilisateurs enregistrés à afficher l'API.

    Si vous vous êtes inscrit à la version bêta de la fonctionnalité de gestion des audiences, sélectionnez l'une des options suivantes :

    • Publique (visible par tous) pour permettre à tous les utilisateurs d'afficher l'API.
    • Utilisateurs authentifiés pour autoriser uniquement les utilisateurs enregistrés à afficher l'API.
    • Audience sélectionnées pour sélectionner les audiences spécifiques que vous souhaitez autoriser à afficher l'API.

    Vous pourrez gérer la visibilité de l'audience ultérieurement, comme décrit dans la section Gérer la visibilité d'une API.

    Image à afficher Pour afficher une image sur la fiche de l'API présente sur la page des API, cliquez sur Sélectionner une image. Dans la boîte de dialogue Sélectionner une image, sélectionnez une image existante, importez une nouvelle image ou indiquez l'URL d'une image externe, puis cliquez sur Sélectionner. Prévisualisez la miniature de l'API, puis cliquez sur Sélectionner. Vous pouvez ajouter une image ultérieurement, comme décrit dans Gérer l'image pour une fiche d'API. Lorsque vous spécifiez l'URL d'une image externe, l'image n'est pas importée dans vos éléments. De plus, le chargement de l'image dans le portail intégré dépendra de sa disponibilité, qui peut être bloquée ou limitée par des règles de sécurité du contenu.
    Catégories

    Ajoutez les catégories auxquelles l'API sera taguée pour permettre aux développeurs d'applications d'identifier les API associées sur la page des API. Pour identifier une catégorie :

    • Sélectionnez une catégorie dans la liste déroulante.
    • Ajoutez une nouvelle catégorie en saisissant son nom, puis en appuyant sur la touche Entrée. La nouvelle catégorie est ajoutée à la page "Catégories" et devient disponible lors de l'ajout ou de la modification d'autres API.

  7. Cliquez sur Enregistrer.

curl

Pour ajouter une API à votre portail en utilisant organizations.sites.apidocs.create :

curl -X POST "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": "IMAGE_URL",
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE,
            "apiProductName": "API_PRODUCT",
         }'

Remplacez les éléments suivants :

  • ORG_NAME par le nom de l'organisation. Par exemple, my-org.
  • SITE_ID par le nom du portail, au format ORG_NAME-PORTAL_NAME, où ORG_NAME est le nom de l'organisation et PORTAL_NAME le nom du portail converti en minuscules sans espaces ni tirets. Par exemple, my-org-myportal.
  • TITLE par l'intitulé. Par exemple, Hello World 2.
  • DESCRIPTION par la description à afficher. Exemple : Simple hello world example.
  • ANON_TRUE_OR_FALSE par true ou false (valeur par défaut), où true active l'accès utilisateur anonyme. Ce paramètre est ignoré si vous êtes inscrit à la version bêta de la fonctionnalité de gestion des audiences.
  • IMAGE_URL par l'URL d'une image externe utilisée pour l'article de catalogue, ou par un chemin d'accès pour les fichiers image stockés dans le portail, par exemple /files/book-tree.jpg. Lorsque vous spécifiez l'URL d'une image externe, l'image n'est pas importée dans vos éléments. De plus, le chargement de l'image dans le portail intégré dépendra de sa disponibilité, qui peut être bloquée ou limitée par des règles de sécurité du contenu.
  • CALLBACK_TRUE_OR_FALSE par true ou false (valeur par défaut), où true oblige les utilisateurs du portail à saisir une URL lors de la gestion de l'application.

  • CATEGORY_ID par l'ID de la catégorie. Exemple : bf6505eb-2a0f-47af-a00a-ded40ac72960. Séparez les différents ID de catégorie par une virgule. Obtenez l'ID de catégorie à l'aide de la commande list API categories.

  • PUBLISHED_TRUE_OR_FALSE avec true ou false (valeur par défaut), où true indique que l'API est accessible au public.

  • API_PRODUCT par le nom du produit d'API Exemple : Hello World 2.

Charge utile de la réponse :

{
  "status": "success",
  "message": "API created",
  "requestId": "1662161889",
  "data": {
    "siteId": "my-org-myportal",
    "title": "Hello World 2",
    "description": "Simple hello world example",
    "modified": "1698948807000",
    "anonAllowed": true,
    "imageUrl": "/files/book-tree.jpg",
    "id": "409405",
    "requireCallbackUrl": true,
    "categoryIds": [
      "88fbfd1d-9300-49f7-bfc2-531ade4c63d4",
      "630c4cf9-109a-48b0-98cc-ef4c12ae4474"
    ],
    "published": true,
    "apiProductName": "Hello World 2"
  }
}

Où :

  • modified: Heure de la dernière modification de l'article de catalogue en millisecondes depuis l'epoch. Par exemple, 1698165480000.
  • id: ID de l'article de catalogue. Par exemple, 399668.

Modifier une API

Une fois que vous avez ajouté une API, utilisez la console ou un appel d'API pour effectuer des modifications.

Cette section fournit un exemple détaillé de la procédure à suivre pour modifier une API existante de votre portail.

Reportez-vous aux sections suivantes pour connaître les paramètres de modification spécifiques.

Console

  1. Accédez au catalogue d'API.
  2. Cliquez sur l'onglet API, s'il n'est pas déjà sélectionné.
  3. Cliquez sur la ligne de l'API que vous souhaitez modifier.
  4. Cliquez sur Modifier.
  5. Sous Détails de l'API, apportez les modifications souhaitées. Consultez les descriptions des options dans la section Ajouter une API.
  6. Cliquez sur Enregistrer.

curl

Une fois que vous avez ajouté une API, effectuez l'appel organizations.sites.apidocs.update pour apporter des modifications.

Cet exemple décrit les étapes requises pour faire passer l'état publié de l'API de votre portail de true à false. Vous pouvez modifier plusieurs paramètres dans un même appel d'API si nécessaire.

  1. Obtenez la liste des API de votre portail à l'aide de organizations.sites.apidocs/list afin de localiser le id généré qui identifie chaque API de manière unique :

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

    Remplacez les éléments suivants :

    • ORG_NAME par le nom de l'organisation. Par exemple, my-org.
    • SITE_ID par le nom du portail, au format ORG_NAME-PORTAL_NAME, où ORG_NAME est le nom de l'organisation et PORTAL_NAME le nom du portail converti en minuscules sans espaces ni tirets. Par exemple, my-org-myportal.

    Charge utile de la réponse :

    {
  "status": "success",
  "message": "one page of apidocs returned",
  "requestId": "1167960478",
  "data": [
    {
      "siteId": "my-org-myportal",
      "title": "Hello New World",
      "description": "Simple hello new world example",
      "specId": "hellowworld",
      "modified": "1695841621000",
      "anonAllowed": true,
      "imageUrl": "/files/camper1.jpg?v=1695841491415",
      "id": "381054",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello New World"
    },
    {
      "siteId": "my-org-myportal",
      "title": "mock-product",
      "description": "Mock product",
      "specId": "apigee spec",
      "modified": "1698956849000",
      "anonAllowed": true,
      "id": "399638",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
      ],
      "published": true,
      "apiProductName": "mock-product"
    },
    {
      "siteId": "my-org-myportal",
      "title": "Hello World 2",
      "description": "Simple hello world example",
      "specId": "hello-new-world",
      "modified": "1698950207000",
      "anonAllowed": true,
      "imageUrl": "/files/book-tree.jpg?v=1698165437881",
      "id": "399668",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello World 2"
    }
  ]
}

    Où :

    • modified: Heure de la dernière modification de l'article de catalogue en millisecondes depuis l'epoch. Par exemple, 1698165480000.
    • id: ID de l'article de catalogue. Par exemple, 399668.

  2. Utilisez l'appel organizations.sites.apidocs.get pour renvoyer les valeurs actuelles d'une API spécifique :

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

    Remplacez les éléments suivants :

    • ORG_NAME par le nom de l'organisation. Par exemple, my-org.
    • SITE_ID par le nom du portail, au format ORG_NAME-PORTAL_NAME, où ORG_NAME est le nom de l'organisation et PORTAL_NAME le nom du portail converti en minuscules sans espaces ni tirets. Par exemple, my-org-myportal.
    • API_DOC par le id généré du document. Exemple : 399668. Utilisez la commande list API docs pour trouver cette valeur.

    Charge utile de la réponse :

    {
  "status": "success",
  "message": "apidoc returned",
  "requestId": "2072952505",
  "data": {
    "siteId": "my-org-myportal",
    "title": "Hello World 2",
    "description": "Simple hello world example",
    "specId": "hello-new-world",
    "modified": "1698950207000",
    "anonAllowed": true,
    "imageUrl": "/files/book-tree.jpg?v=1698165437881",
    "id": "399668",
    "categoryIds": [
      "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
      "61c1014c-89c9-40e6-be3c-69cca3505620"
    ],
    "published": true,
    "apiProductName": "Hello World 2"
  }
}

  3. Incluez les valeurs modifiables que vous souhaitez conserver dans l'appel organizations.sites.apidocs.update, puis modifiez celles que vous souhaitez modifier. Si vous omettez une ligne, la valeur par défaut sera utilisée. Pour cet exemple, modifiez le paramètre published de true à false :

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": "IMAGE_URL",
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": false,
        "apiProductName": "API_PRODUCT",
     }'

    Remplacez les éléments suivants :

    • TITLE par l'intitulé. Par exemple, Hello World 2.
    • DESCRIPTION par la description à afficher. Exemple : Simple hello world example.
    • ANON_TRUE_OR_FALSE par true ou false (valeur par défaut), où true active l'accès utilisateur anonyme. Ce paramètre est ignoré si vous êtes inscrit à la version bêta de la fonctionnalité de gestion des audiences.
    • IMAGE_URL par l'URL d'une image externe utilisée pour l'article de catalogue, ou par un chemin d'accès pour les fichiers image stockés dans le portail, par exemple /files/book-tree.jpg. Lorsque vous spécifiez l'URL d'une image externe, l'image n'est pas importée dans vos éléments. De plus, le chargement de l'image dans le portail intégré dépendra de sa disponibilité, qui peut être bloquée ou limitée par des règles de sécurité du contenu.
    • CALLBACK_TRUE_OR_FALSE par true ou false (valeur par défaut), où true oblige les utilisateurs du portail à saisir une URL lors de la gestion de l'application.
    • CATEGORY_ID par l'ID de la catégorie. Exemple : bf6505eb-2a0f-47af-a00a-ded40ac72960. Séparez les différents ID de catégorie par une virgule. Obtenez l'ID de catégorie à l'aide de la commande list API categories.
    • API_PRODUCT par le nom du produit d'API Exemple : Hello World 2.

    Charge utile de la réponse :

    {
  "status": "success",
  "message": "ApiDoc updated",
  "requestId": "197181831",
  "data": {
    "siteId": "my-org-myportal",
    "title": "Hello World 2",
    "description": "Simple hello world example.",
    "modified": "1698884328000",
    "anonAllowed": true,
    "imageUrl": "/files/book-tree.jpg",
    "id": "408567",
    "requireCallbackUrl": true,
    "categoryIds": [
      "88fbfd1d-9300-49f7-bfc2-531ade4c63d4",
      "630c4cf9-109a-48b0-98cc-ef4c12ae4474"
    ],
    "published": PUBLISHED_TRUE_OR_FALSE,
    "apiProductName": "Hello World 2"
  }
}

Publier ou annuler la publication d'une API

Le processus de publication consiste à mettre vos API à la disposition des développeurs d'applications afin qu'ils puissent les utiliser.

Pour publier ou annuler la publication d'une API sur votre portail :

Console

  1. Accédez au catalogue d'API.
  2. Cliquez sur l'onglet API, s'il n'est pas déjà sélectionné.
  3. Cliquez sur la ligne de l'API que vous souhaitez modifier.
  4. Cliquez sur Modifier.
  5. Sous Détails de l'API, cochez ou décochez la case Publié (répertorié dans le catalogue) pour publier ou annuler la publication de l'API sur votre portail, respectivement.
  6. Cliquez sur Enregistrer.

curl

Incluez l'un des éléments suivants dans l'appel update :

  "published": true,    # API is published to your portal
  "published": false,   # API is not published in your portal

Pour modifier l'API :

  1. Utilisez l'appel organizations.sites.apidocs.get pour renvoyer les valeurs actuelles :

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

  2. Utilisez l'appel organizations.sites.apidocs.update pour modifier l'API. Incluez les valeurs modifiables que vous souhaitez conserver et modifiez celles que vous souhaitez modifier. Si vous omettez un paramètre modifiable, la valeur par défaut sera utilisée.

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT",
     }'

Consultez la page Modifier une API pour obtenir un exemple détaillé des étapes, des variables et de la charge utile renvoyée.

Gérer la visibilité d'une API

Gérer la visibilité d'une API page dans votre portail pour donner accès aux publics suivants :

Gérer la visibilité d'une API dans votre portail :

Console

  1. Accédez au catalogue d'API.
  2. Cliquez sur l'onglet API, s'il n'est pas déjà sélectionné.
  3. Cliquez sur la ligne de l'API que vous souhaitez modifier.
  4. Cliquez sur Modifier.

  5. Sélectionnez le paramètre de visibilité. Si vous vous êtes inscrit à la version bêta de la fonctionnalité des audiences, sélectionnez l'une des options suivantes sous Visibilité de l'API :

    • Public (visible to anyone) (Public (visible par tous)), pour autoriser tous les utilisateurs à afficher la page
    • Utilisateurs authentifiés pour autoriser uniquement les utilisateurs enregistrés à afficher la page.
    • Audiences sélectionnées pour sélectionner les audiences spécifiques que vous souhaitez autoriser à afficher la page Consultez la page Gérer les audiences pour votre portail.

    Sinon, sélectionnez l'une des options suivantes sous Audience :

    • Utilisateurs anonymes pour autoriser tous les utilisateurs à afficher la page.
    • Utilisateurs enregistrés pour autoriser uniquement les utilisateurs enregistrés à afficher la page.

  6. Cliquez sur Envoyer.

curl

Si vous êtes inscrit à la version bêta de la fonctionnalité de gestion des audiences, utilisez la console pour gérer ces audiences.

Si vous n'êtes pas inscrit à la fonctionnalité de gestion des audiences, la visibilité est gérée à l'aide de anonAllowed.

Incluez l'un des éléments suivants dans l'appel update :

  # When not enrolled in the beta release of the audience management feature:

  "anonAllowed": true,      # Anonymous users can see the API
  "anonAllowed": false,     # Only registered users can see the API

Pour modifier l'API :

  1. Utilisez l'appel organizations.sites.apidocs.get pour renvoyer les valeurs actuelles :

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

  2. Utilisez l'appel organizations.sites.apidocs.update pour modifier l'API. Incluez les valeurs modifiables que vous souhaitez conserver et modifiez celles que vous souhaitez modifier. Si vous omettez un paramètre modifiable, la valeur par défaut sera utilisée.

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT",
     }'

Consultez la page Modifier une API pour obtenir un exemple détaillé des étapes, des variables et de la charge utile renvoyée.

Gérer l'URL de rappel pour une API

Gérez l'URL de rappel pour une API. Consultez la page À propos des URL de rappel.

Pour gérer l'URL de rappel d'une API, procédez comme suit :

Console

  1. Accédez au catalogue d'API.
  2. Cliquez sur l'onglet API, s'il n'est pas déjà sélectionné.
  3. Cliquez sur la ligne de l'API que vous souhaitez modifier.
  4. Cliquez sur Modifier.
  5. SousDétails de l'API, sélectionnez ou désélectionnez Exiger des développeurs qu'ils spécifient une URL de rappel pour spécifier qu'une URL de rappel est requise ou non, respectivement.
  6. Cliquez sur Enregistrer.

curl

Incluez l'un des éléments suivants dans l'appel update :

  "requireCallbackUrl": true,    # Portal user is required to input a URL
  "requireCallbackUrl": false,   # Portal user is not required to input a URL

Pour modifier l'API :

  1. Utilisez l'appel organizations.sites.apidocs.get pour renvoyer les valeurs actuelles :

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

  2. Utilisez l'appel organizations.sites.apidocs.update pour modifier l'API. Incluez les valeurs modifiables que vous souhaitez conserver et modifiez celles que vous souhaitez modifier. Si vous omettez un paramètre modifiable, la valeur par défaut sera utilisée.

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT",
     }'

Consultez la page Modifier une API pour obtenir un exemple détaillé des étapes, des variables et de la charge utile renvoyée.

Gérer l'image pour une fiche d'API

Gérez l'image qui s'affiche avec une fiche d'API sur la page des API en ajoutant ou en modifiant l'image actuelle.

Pour gérer l'image d'une fiche API :

Console

  1. Accédez au catalogue d'API.
  2. Cliquez sur l'onglet API, s'il n'est pas déjà sélectionné.
  3. Cliquez sur la ligne de l'API que vous souhaitez modifier.
  4. Cliquez sur Modifier.

  5. Sous Détails de l'API :

    • Cliquez sur Sélectionner une image pour spécifier une image si aucune image n'est sélectionnée.
    • Cliquez sur Modifier l'image pour spécifier une autre image.
    • Dans l'image, cliquez sur x pour la supprimer.

    Lorsque vous spécifiez une image, spécifiez soit une image avec une URL externe utilisée pour l'article de catalogue, soit un chemin d'accès pour les fichiers image stockés dans le portail, par exemple /files/book-tree.jpg. Lorsque vous spécifiez l'URL d'une image externe, l'image n'est pas importée dans vos éléments. De plus, le chargement de l'image dans le portail intégré dépendra de sa disponibilité, qui peut être bloquée ou limitée par des règles de sécurité du contenu.

  6. Cliquez sur Enregistrer.

curl

Incluez les éléments suivants dans l'appel update :

  # Omit line for no image file

  "imageUrl": "IMAGE_URL"    # URL of the external image or name of the image file

Pour modifier l'API :

  1. Utilisez l'appel organizations.sites.apidocs.get pour renvoyer les valeurs actuelles :

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

  2. Utilisez l'appel organizations.sites.apidocs.update pour modifier l'API. Incluez les valeurs modifiables que vous souhaitez conserver et modifiez celles que vous souhaitez modifier. Si vous omettez un paramètre modifiable, la valeur par défaut sera utilisée.

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT",
     }'

Consultez la page Modifier une API pour obtenir un exemple détaillé des étapes, des variables et de la charge utile renvoyée.

Ajouter un tag de catégorie à une API

L'utilisation de catégories aide les développeurs d'applications à découvrir les API associées. Consultez également la section Gérer les catégories.

Pour ajouter un tag de catégorie à une API :

Console

  1. Accédez au catalogue d'API.
  2. Cliquez sur l'onglet API, s'il n'est pas déjà sélectionné.
  3. Cliquez sur la ligne de l'API que vous souhaitez modifier.
  4. Cliquez sur Modifier.

  5. Cliquez dans le champ Catégories et effectuez l'une des opérations suivantes :

    • Sélectionnez une catégorie dans la liste déroulante.
    • Ajoutez une nouvelle catégorie en saisissant son nom, puis en appuyant sur la touche Entrée. La nouvelle catégorie est ajoutée à la page Catégories et devient disponible lors de l'ajout ou de la modification d'autres API.

  6. Répétez l'opération pour taguer l'API à d'autres catégories.

  7. Cliquez sur Enregistrer.

curl

Incluez les éléments suivants dans l'appel update :

  # Omit line for no categories

  "categoryIds": [
      "CATEGORY_ID1",      # A category ID number
      "CATEGORY_ID2"       # A category ID number
    ],

Utilisez la commande list categories pour obtenir les numéros d'ID de catégorie.

Pour modifier l'API :

  1. Utilisez l'appel organizations.sites.apidocs.get pour renvoyer les valeurs actuelles :

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

  2. Utilisez l'appel organizations.sites.apidocs.update pour modifier l'API. Incluez les valeurs modifiables que vous souhaitez conserver et modifiez celles que vous souhaitez modifier. Si vous omettez un paramètre modifiable, la valeur par défaut sera utilisée.

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT",
     }'

Consultez la page Modifier une API pour obtenir un exemple détaillé des étapes, des variables et de la charge utile renvoyée.

Modifier l'intitulé et la description

Pour modifier l'intitulé et la description, procédez comme suit :

Console

  1. Accédez au catalogue d'API.
  2. Cliquez sur l'onglet API, s'il n'est pas déjà sélectionné.
  3. Cliquez sur la ligne de l'API que vous souhaitez modifier.
  4. Cliquez sur Modifier.
  5. Modifiez les champs Intitulé et Description, si nécessaire.
  6. Cliquez sur Enregistrer.

curl

Incluez les éléments suivants dans l'appel update :

  "title": "TITLE",              # Display title
  "description": "DESCRIPTION",  # Display description

Pour modifier l'API :

  1. Utilisez l'appel organizations.sites.apidocs.get pour renvoyer les valeurs actuelles :

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

  2. Utilisez l'appel organizations.sites.apidocs.update pour modifier l'API. Incluez les valeurs modifiables que vous souhaitez conserver et modifiez celles que vous souhaitez modifier. Si vous omettez un paramètre modifiable, la valeur par défaut sera utilisée.

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT",
     }'

Consultez la page Modifier une API pour obtenir un exemple détaillé des étapes, des variables et de la charge utile renvoyée.

Supprimer une API

Pour supprimer une API de votre portail, :

Console

  1. Accédez au catalogue d'API.
  2. Sélectionnez l'onglet API s'il n'est pas déjà sélectionné.
  3. Placez votre curseur sur l'API de la liste pour afficher le menu d'actions.
  4. Cliquez sur Supprimer.

curl

Pour supprimer une API de votre portail organizations.sites.apidocs.delete :

curl -X DELETE "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Remplacez les éléments suivants :

  • ORG_NAME par le nom de l'organisation. Par exemple, my-org.
  • SITE_ID par le nom du portail, au format ORG_NAME-PORTAL_NAME, où ORG_NAME est le nom de l'organisation et PORTAL_NAME le nom du portail converti en minuscules sans espaces ni tirets. Par exemple, my-org-myportal.
  • API_DOC par le id généré du document. Exemple : 399668. Utilisez la commande list API docs pour trouver cette valeur.

Charge utile de la réponse :

{
  "status":"success",
  "message":"Apidoc deleted",
  "requestId":"645138256"
}

Gérer la documentation de l'API

Les sections suivantes expliquent comment mettre à jour, télécharger ou supprimer la documentation sur l'API.

Mettre à jour la documentation de l'API

Une fois l'API publiée, vous pouvez à tout moment importer une nouvelle version du document OpenAPI ou GraphQL.

Pour importer une autre version de la documentation de l'API :

Console

  1. Accédez au catalogue d'API.
  2. Cliquez sur l'onglet API, s'il n'est pas déjà sélectionné.
  3. Cliquez sur la ligne de l'API que vous souhaitez modifier.
  4. Cliquez sur Modifier.
  5. Dans le volet Documentation de l'API, sélectionnez l'une des options suivantes :
    • Document OpenAPI
    • Schéma GraphQL
  6. Cliquez sur Sélectionner un document, puis sélectionnez la dernière version du document.
  7. Pour GraphQL, spécifiez l'URL du point de terminaison.
  8. Cliquez sur Enregistrer.

curl

Pour mettre à jour le contenu de la documentation OpenAPI ou GraphQL à l'aide de organizations.sites.apidocs.updateDocumentation, procédez comme suit :

OpenAPI

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"oasDocumentation": {
           "spec":{ "displayName":"DISPLAY_NAME",
                    "contents":"CONTENTS"}
            }
        }'

Remplacez les éléments suivants :

  • ORG_NAME par le nom de l'organisation. Par exemple, my-org.
  • SITE_ID par le nom du portail, au format ORG_NAME-PORTAL_NAME, où ORG_NAME est le nom de l'organisation et PORTAL_NAME le nom du portail converti en minuscules sans espaces ni tirets. Par exemple, my-org-myportal.
  • API_DOC par le id généré du document. Exemple : 399668. Utilisez la commande list API docs pour trouver cette valeur.
  • DISPLAY_NAME par l'intitulé de la documentation d'API. Exemple : Hello World 2.
  • CONTENTS par la chaîne de contenu de la documentation d'API, encodée en base64. La plupart des environnements de développement contiennent un utilitaire de conversion base64. De nombreux outils de conversion en ligne sont également disponibles.

Charge utile de la réponse :

{
 "status":"success",
 "message":"Api documentation updated",
 "requestId":"645138278"
 "data": {
   "oasDocumentation": {
     "spec": {
        "displayName": "Hello World 2"
      },
     "Format": "YAML"
   }
 }
}

GraphQL

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"graphqlDocumentation": {
         "schema":{"displayName":"DISPLAY_NAME",
         "contents":"CONTENTS"},
         "endpointUri": "ENDPOINT_URI"
          }
      }'

Remplacez les éléments suivants :

  • ORG_NAME par le nom de l'organisation. Par exemple, my-org.
  • SITE_ID par le nom du portail, au format ORG_NAME-PORTAL_NAME, où ORG_NAME est le nom de l'organisation et PORTAL_NAME le nom du portail converti en minuscules sans espaces ni tirets. Par exemple, my-org-myportal.
  • API_DOC par le id généré du document. Exemple : 399668. Utilisez la commande list API docs pour trouver cette valeur.
  • DISPLAY_NAME par l'intitulé de la documentation d'API. Exemple : Hello World 2.
  • ENDPOINT_URI par le nom de domaine de votre URI de point de terminaison. Exemple : https://demo.google.com/graphql.
  • CONTENTS par la chaîne de contenu de la documentation d'API, encodée en base64. La plupart des environnements de développement contiennent un utilitaire de conversion base64. De nombreux outils de conversion en ligne sont également disponibles.

Charge utile de la réponse :

{
 "status":"success",
 "message":"Api documentation updated",
 "requestId":"645138278"
  "data": {
    "graphqlDocumentation": {
      "schema": {
        "displayName": "Hello World 2"
      },
     "endpointUri": "https://demo.google.com/graphql"
    }
  }
}

La documentation de référence de l'API est affichée à partir du document et ajoutée à la page des API du portail en ligne.

Télécharger la documentation d'API

Une fois l'API publiée, vous pouvez à tout moment télécharger la documentation de référence OpenAPI ou GraphQL publiée sur votre portail.

Pour télécharger la documentation d'API à l'aide de organizations.sites.apidocs.getDocumentation, procédez comme suit :

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Remplacez les éléments suivants :

  • ORG_NAME par le nom de l'organisation. Par exemple, my-org.
  • SITE_ID par le nom du portail, au format ORG_NAME-PORTAL_NAME, où ORG_NAME est le nom de l'organisation et PORTAL_NAME le nom du portail converti en minuscules sans espaces ni tirets. Par exemple, my-org-myportal.

  • API_DOC par le id généré du document. Exemple : 399668. Utilisez la commande list API docs pour trouver cette valeur.

    Charge utile de la réponse :

{
  "status":"success",
  "message":"Api documentation downloaded",
  "requestId":"645138256",
  "data": {
      "oasDocumentation":{
          "spec":{
            "displayName":"Hello World 2",
            "contents":"c3dhZ2dlcjogJzIuMCcKaW5mbzoKICBkZXNlI ..."
          },
          "Format": YAML
      }
  }
}

Où :

contents: : chaîne de contenu de la documentation d'API, encodée en base64.

Supprimer la documentation d'API

Pour supprimer la documentation d'API :

Console

  1. Accédez au catalogue d'API.
  2. Cliquez sur l'onglet API, s'il n'est pas déjà sélectionné.
  3. Cliquez sur la ligne de l'API que vous souhaitez modifier.
  4. Cliquez sur Modifier.
  5. Dans le volet Documentation d'API, sélectionnez Aucune documentation.
  6. Cliquez sur Enregistrer.

curl

Pour supprimer le contenu d'une documentation d'API à l'aide d'une API, vous devez effacer les paramètres existants en envoyant un corps de requête vide.

Pour envoyer un corps de requête vide et effacer le contenu existant à l'aide de organizations.sites.apidocs.updateDocumentation :

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{}'

Remplacez les éléments suivants :

  • ORG_NAME par le nom de l'organisation. Par exemple, my-org.
  • SITE_ID par le nom du portail, au format ORG_NAME-PORTAL_NAME, où ORG_NAME est le nom de l'organisation et PORTAL_NAME le nom du portail converti en minuscules sans espaces ni tirets. Par exemple, my-org-myportal.
  • API_DOC par le id généré du document. Exemple : 399668. Utilisez la commande list API docs pour trouver cette valeur.

Charge utile de la réponse :

{
   "status":"success",
   "message":"Api documentation updated",
   "requestId":"645138279"
}

Gérer les catégories

Taguez une API à l'aide de catégories pour permettre aux développeurs d'applications d'identifier les API associées sur la page des API du portail en ligne. Ajoutez et gérez des catégories, comme décrit dans les sections suivantes.

Découvrir les catégories

Utilisez la console ou la commande curl pour afficher les catégories.

Console

Pour afficher la page "Catégories" :

  1. Sélectionnez Publier > Portails et sélectionnez votre portail.
  2. Cliquez sur Catalogue d'API sur la page d'accueil du portail.
    Vous pouvez également sélectionner Catalogue d'API dans le menu déroulant du portail dans la barre de navigation supérieure.

  3. Cliquez sur l'onglet Catégories. L'onglet Catégories du catalogue d'API affiche la liste des catégories définies pour votre portail.

    Onglet &quot;Catégories&quot; affichant le nom de la catégorie, ainsi que le nom et le nombre total des API attribuées

    Onglet &quot;Catégories&quot; affichant le nom de la catégorie, ainsi que le nom et le nombre total des API attribuées

    Comme le montre la figure précédente, la page des API vous permet d'effectuer les opérations suivantes :

curl

Pour répertorier des catégories à l'aide de organizations.sites.apicategories.list :

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Remplacez les éléments suivants :

  • ORG_NAME par le nom de l'organisation. Par exemple, my-org.
  • SITE_ID par le nom du portail, au format ORG_NAME-PORTAL_NAME, où ORG_NAME est le nom de l'organisation et PORTAL_NAME le nom du portail converti en minuscules sans espaces ni tirets. Par exemple, my-org-myportal.

Charge utile de la réponse :

{
  "data": [
    {
      "siteId": "my-org-myportal",
      "name": "Get Started",
      "id": "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
    },
    {
      "siteId": "my-org-myportal",
      "name": "Test",
      "id": "61c1014c-89c9-40e6-be3c-69cca3505620"
    }
  ],
  "status": "success",
  "message": "all ApiCategory items returned",
  "requestId": "602661435"
}

Où :

  • id: ID de l'article de catégorie. Par exemple, 61c1014c-89c9-40e6-be3c-69cca3505620.

Ajouter une catégorie

Pour ajouter une catégorie :

Console

  1. Accédez à la page "Catégories".
  2. Cliquez sur Ajouter.
  3. Saisissez le nom de la nouvelle catégorie.
  4. Si vous le souhaitez, sélectionnez une ou plusieurs API à taguer à la catégorie.
  5. Cliquez sur Créer.

curl

Pour ajouter une catégorie à l'aide de organizations.sites.apicategories.create :

curl  -X POST "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

Remplacez les éléments suivants :

  • ORG_NAME par le nom de l'organisation. Par exemple, my-org.
  • SITE_ID par le nom du portail, au format ORG_NAME-PORTAL_NAME, où ORG_NAME est le nom de l'organisation et PORTAL_NAME le nom du portail converti en minuscules sans espaces ni tirets. Par exemple, my-org-myportal.
  • CATEGORY_NAME par le nom de la catégorie. Exemple : demo-backend.

Charge utile de la réponse :

{
  "data": {
    "siteId": "my-org-myportal",
    "name": "demo-backend",
    "id": "ed0b6c1d-eb49-419f-8475-9a428ed5b8d1"
  },
  "status": "success",
  "message": "API category created",
  "requestId": "295617049"
}

Modifier une catégorie

Pour modifier une catégorie, procédez comme suit :

Console

  1. Accédez à la page "Catégories".
  2. Placez le curseur sur la catégorie que vous souhaitez modifier pour afficher le menu d'actions.
  3. Cliquez sur Modifier.
  4. Modifiez le nom de la catégorie.
  5. Ajoutez ou supprimez des tags d'API.
  6. Cliquez sur Enregistrer.

curl

Pour modifier une catégorie à l'aide de organizations.sites.apicategories.patch :

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID"  \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

Remplacez les éléments suivants :

  • ORG_NAME par le nom de l'organisation. Par exemple, my-org.
  • SITE_ID par le nom du portail, au format ORG_NAME-PORTAL_NAME, où ORG_NAME est le nom de l'organisation et PORTAL_NAME le nom du portail converti en minuscules sans espaces ni tirets. Par exemple, my-org-myportal.
  • CATEGORY_ID par l'ID de la catégorie. Exemple : bf6505eb-2a0f-47af-a00a-ded40ac72960. Obtenez l'ID de catégorie à l'aide de la commande list API categories.
  • CATEGORY_NAME par le nom de la catégorie. Exemple : demo-backend.

Charge utile de la réponse :

{
  "data": {
    "siteId": "my-org-myportal",
    "name": "demo-backend-test",
    "id": "ed0b6c1d-eb49-419f-8475-9a428ed5b8d1"
  },
  "status": "success",
  "message": "ApiCategory updated",
  "requestId": "192211979"
}

Supprimer une catégorie

Lorsque vous supprimez une catégorie, tous les tags d'API de cette catégorie sont également supprimés.

Pour supprimer une catégorie :

Console

  1. Accédez à la page "Catégories".
  2. Placez le curseur sur la catégorie que vous souhaitez modifier pour afficher le menu d'actions.
  3. Cliquez sur Supprimer.
  4. Cliquez sur Supprimer pour confirmer.

curl

Pour supprimer une catégorie à l'aide de organizations.sites.apicategories.delete :

curl -X DELETE "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json"

Remplacez les éléments suivants :

  • ORG_NAME par le nom de l'organisation. Par exemple, my-org.
  • SITE_ID par le nom du portail, au format ORG_NAME-PORTAL_NAME, où ORG_NAME est le nom de l'organisation et PORTAL_NAME le nom du portail converti en minuscules sans espaces ni tirets. Par exemple, my-org-myportal.
  • CATEGORY_ID par l'ID de la catégorie. Exemple : bf6505eb-2a0f-47af-a00a-ded40ac72960. Obtenez l'ID de catégorie à l'aide de la commande list API categories.

Charge utile de la réponse :

{
  "status": "success",
  "message": "ApiCategory deleted",
  "requestId": "1610396471"
}

Résoudre les problèmes liés à vos API publiées

Les sections suivantes fournissent des informations pour vous aider à résoudre les erreurs spécifiques liées à nos API publiées.

Erreur : Échec de la récupération de l'erreur renvoyée lors de l'utilisation de "Essayer cette API"

Lorsque vous utilisez Essayer cette API, si l'erreur TypeError: Failed to fetch est renvoyée, voici les causes et les résolutions possibles :

Erreur : Champ d'en-tête de requête non autorisé

Lorsque vous utilisez Essayer cette API, si vous recevez une erreur Request header field not allowed, semblable à l'exemple ci-dessous, vous devrez peut-être mettre à jour les en-têtes compatibles avec la règle CORS. Exemple :

field content-type is not allowed by Access-Control-Allow-Headers in preflight
response

Dans cet exemple, vous devez ajouter l'en-tête content-type à la section Access-Control-Allow-Headers de votre règle AssignMessage CORS, comme décrit dans la section Associer une règle CORS à un nouveau proxy d'API.

Erreur : Accès refusé lors de l'appel d'un proxy d'API à l'aide d'OAuth 2.0

La règle OAuthV2 de la console Google Cloud renvoie une réponse à un jeton qui contient certaines propriétés non conformes à la norme RFC. Par exemple, la règle renvoie un jeton avec la valeur BearerToken, au lieu de la valeur Bearer conforme à la norme RFC. Cette réponse token_type non valide peut entraîner une erreur Access denied lors de l'utilisation de "Essayer cette API".

Pour résoudre ce problème, vous pouvez créer une règle JavaScript ou AssignMessage afin de transformer la sortie dans un format conforme. Pour en savoir plus, consultez la section Comportement non conforme à la norme RFC.