Publier vos API

Vous consultez la documentation d'Apigee Edge.
Accédez à la documentation sur Apigee X. info

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 en savoir plus sur les instantanés, consultez la section Qu'est-ce qu'un instantané ?)

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 en savoir plus. 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

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.

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 illustré dans la figure suivante.

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

Qu'est-ce qu'un instantané ?

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, vous effectuez un instantané du document OpenAPI ou GraphQL pour afficher la documentation de référence de l'API. Cet instantané représente une version spécifique du document. Si vous modifiez le document, vous pouvez décider d'effectuer un autre instantané afin de refléter les dernières modifications apportées dans la documentation de référence de l'API.

À 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 en savoir plus, 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 "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 OAuth2.

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 Ajoutez la compatibilité CORS à votre proxy d'API. Pour plus de commodité, utilisez l' exemple de solution CORS fourni sur GitHub ou suivez les étapes décrites dans la section Ajouter la compatibilité CORS à un proxy d'API.
Authentification de base Procédez comme suit :
  1. Ajoutez la compatibilité CORS à votre proxy d'API. Pour plus de commodité, utilisez l' exemple de solution CORS fourni sur GitHub ou suivez les étapes décrites dans la section Ajouter la compatibilité CORS à un proxy d'API.
  2. Dans la règle "Add CORS AssignMessage", 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>
OAuth2
  1. Ajoutez la compatibilité CORS à votre proxy d'API. Pour plus de commodité, utilisez l' exemple de solution CORS fourni sur GitHub ou suivez les étapes décrites dans la section Ajouter la compatibilité CORS à un proxy d'API.
  2. Dans la règle "Add CORS AssignMessage", 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 OAuth2. Pour plus de commodité, utilisez l' exemple de solution OAuth2 fourni sur GitHub ou procédez comme suit :
    • Assurez-vous que l'élément <GrantType> de la règle OAuth2 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 OAuth2 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 l'UI ou la commande curl pour afficher les API qui se trouvent dans votre portail.

UI

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

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:

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer ACCESS_TOKEN"

Remplacez les éléments suivants :

  • ORG_NAME par le nom de l'organisation. Exemple :my-org
  • SITE_ID avec 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. Exemple : my-org-myportal.
  • ACCESS_TOKEN avec le jeton d'authentification utilisé pour accéder à l'API Apigee Edge. Pour en savoir plus sur l'authentification et les jetons, consultez la section Authentifier l'accès à l'API Edge.

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",
  "data": [
    {
      "id": 622759,
      "siteId": "my-org-myportal",
      "title": "Test",
      "description": "",
      "published": false,
      "visibility": false,
      "apiId": "apiproducttest18",
      "apiProductName": "apiproduct_test18",
      "edgeAPIProductName": "apiproduct_test18",
      "specId": null,
      "specContent": null,
      "specTitle": null,
      "snapshotExists": false,
      "snapshotModified": null,
      "modified": 1724144471000,
      "anonAllowed": false,
      "imageUrl": null,
      "snapshotState": null,
      "requireCallbackUrl": false,
      "categoryIds": [],
      "specFormat": null,
      "specModified": null,
      "snapshotOutdated": false,
      "snapshotSourceMissing": false,
      "graphqlSchema": null,
      "graphqlEndpointUrl": null,
      "graphqlSchemaDisplayName": null,
      "grpcFileName": null,
      "grpcZipContent": null
    }
  ],
  "code": null,
  "request_id": "1452867334",
  "error_code": null,
  "next_page_token": ""
}

Où :

  • modified: heure de la dernière modification de l'article de catalogue en millisecondes depuis l'epoch. Exemple :1698165480000
  • id: ID de l'élément de catalogue. 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, nextPageToken est renseigné avec un jeton:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE" \
   -H "Authorization: Bearer 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",
  "data": [
    {
      "id": 638007,
      "siteId": "tsnow-mint-liztest",
      "title": "Testing",
      "description": "",
      "published": false,
      "visibility": false,
      "apiId": "testcatalog",
      "apiProductName": "testcatalog",
      "edgeAPIProductName": "testcatalog",
      "specId": "Petstore",
      "specContent": null,
      "specTitle": null,
      "snapshotExists": true,
      "snapshotModified": 1726508367000,
      "modified": 1728582504000,
      "anonAllowed": false,
      "imageUrl": null,
      "snapshotState": "OK_SUBMITTED",
      "requireCallbackUrl": false,
      "categoryIds": [],
      "specFormat": "YAML",
      "specModified": null,
      "snapshotOutdated": false,
      "snapshotSourceMissing": false,
      "graphqlSchema": null,
      "graphqlEndpointUrl": null,
      "graphqlSchemaDisplayName": null,
      "grpcFileName": null,
      "grpcZipContent": null
    }
  ],
  "code": null,
  "request_id": "1068810934",
  "error_code": null,
  "next_page_token": ""
}

  • Jeton de page: utilisez pageToken pour récupérer les pages suivantes lorsqu'il en existe plusieurs:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN" \
      -H "Authorization: Bearer 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. Par exemple, 7zcqrin9l6xhi4nbrb9.

Ajouter une API

Utilisez l'UI ou la commande curl pour ajouter des API à votre portail:

UI

Pour ajouter une API à votre portail :

  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é 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 sur votre portail.
    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 à afficher 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 Sélectionner un document.
    3. Effectuez l'une des opérations suivantes :
      • Cliquez sur l'onglet My Specs (Mes spécifications), puis sélectionnez une spécification dans la boutique de spécifications.
      • Cliquez sur l'onglet Importer un fichier, puis importez un fichier.
      • Cliquez sur l'onglet Importer depuis une URL et importez une spécification à partir d'une URL.
    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 section Gérer l'instantané du document.

    Visibilité de l'API

    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.
    • Audiences 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 dans votre portail.

    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 une image avec une URL 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 :

curl -X POST "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer 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. Exemple :my-org
  • SITE_ID avec 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. Exemple : my-org-myportal.
  • ACCESS_TOKEN avec le jeton d'authentification utilisé pour accéder à l'API Apigee Edge. Pour en savoir plus sur l'authentification et les jetons, consultez la section Authentifier l'accès à l'API Edge.
  • TITLE par l'intitulé. Par exemple, Hello World 2.
  • DESCRIPTION par la description à afficher. Par exemple, Simple hello world example.
  • ANON_TRUE_OR_FALSE avec true ou false (valeur par défaut), où true signifie que cette API a une visibilité publique et peut être consultée de manière anonyme. Sinon, seuls les utilisateurs enregistrés peuvent la consulter.
  • 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. Une fois publiée, vous pouvez autoriser l'accès à tous les utilisateurs, aux utilisateurs authentifiés ou à des utilisateurs spécifiques.
  • API_PRODUCT par le nom du produit d'API Exemple : Hello World 2.

Charge utile de la réponse :

{
  "status": "success",
  "message": "API created",
  "data": {
    "id": 662423,
    "siteId": "my-org-myportal",
    "title": "My Test Catalog 4",
    "description": "",
    "published": false,
    "visibility": false,
    "apiId": "uxb9wjua",
    "apiProductName": "uXB9wJUa",
    "edgeAPIProductName": "uXB9wJUa",
    "specId": null,
    "specContent": null,
    "specTitle": null,
    "snapshotExists": false,
    "snapshotModified": null,
    "modified": 1729635493000,
    "anonAllowed": false,
    "imageUrl": null,
    "snapshotState": null,
    "requireCallbackUrl": false,
    "categoryIds": [],
    "specFormat": null,
    "specModified": null,
    "snapshotOutdated": null,
    "snapshotSourceMissing": false,
    "graphqlSchema": null,
    "graphqlEndpointUrl": null,
    "graphqlSchemaDisplayName": null,
    "grpcFileName": null,
    "grpcZipContent": null
  },
  "code": null,
  "request_id": "893346193",
  "error_code": null
}

Où :

  • modified: heure de la dernière modification de l'article de catalogue en millisecondes depuis l'epoch. Exemple :1698165480000
  • id: ID de l'élément de catalogue. Exemple :399668

Modifier une API

Une fois que vous avez ajouté une API, utilisez l'UI 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.

UI

Pour modifier une API, procédez comme suit :

  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 (icône de modification).
  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, utilisez l'appel 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. Pour localiser le id généré qui identifie chaque API de manière unique, obtenez la liste des API de votre portail, comme décrit dans la section Explorer les API.

  2. Renvoyer les valeurs actuelles d'une API spécifique:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
-H "Authorization: Bearer ACCESS_TOKEN"

    Remplacez les éléments suivants :

    • ORG_NAME par le nom de l'organisation. Exemple :my-org
    • SITE_ID avec 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. 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.
    • ACCESS_TOKEN avec le jeton d'authentification utilisé pour accéder à l'API Apigee Edge. Pour en savoir plus sur l'authentification et les jetons, consultez la section Authentifier l'accès à l'API Edge.

    Charge utile de la réponse :

    {
  "status": "success",
  "message": "apidoc returned",
  "data": {
    "id": 662423,
    "siteId": "my-org-myportal",
    "title": "My Test Catalog 4",
    "description": "",
    "published": false,
    "visibility": false,
    "apiId": "uxb9wjua",
    "apiProductName": "uXB9wJUa",
    "edgeAPIProductName": "uXB9wJUa",
    "specId": null,
    "specContent": null,
    "specTitle": null,
    "snapshotExists": false,
    "snapshotModified": null,
    "modified": 1729635493000,
    "anonAllowed": false,
    "imageUrl": null,
    "snapshotState": null,
    "requireCallbackUrl": false,
    "categoryIds": [],
    "specFormat": null,
    "specModified": null,
    "snapshotOutdated": false,
    "snapshotSourceMissing": false,
    "graphqlSchema": null,
    "graphqlEndpointUrl": null,
    "graphqlSchemaDisplayName": null,
    "grpcFileName": null,
    "grpcZipContent": null
  },
  "code": null,
  "request_id": "601210268",
  "error_code": null
}

  1. Incluez les valeurs modifiables que vous souhaitez conserver dans l'appel update, puis modifiez celles que vous souhaitez modifier. Si vous omettez une ligne, la valeur par défaut est utilisée. Pour cet exemple, remplacez le paramètre publié false par true:

    curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
 -H "Authorization: Bearer ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
    "title": "TITLE",
    "anonAllowed": true,
    "published": true
 }'

    Remplacez les éléments suivants :

    • TITLE par l'intitulé. Exemple :Hello World 2

    Charge utile de la réponse :

    {
  "status": "success",
  "message": "ApiDoc updated",
  "data": {
    "id": 662423,
    "siteId": "my-org-myportal",
    "title": "My Test Catalog 4",
    "description": "",
    "published": true,
    "visibility": true,
    "apiId": "uxb9wjua",
    "apiProductName": "uXB9wJUa",
    "edgeAPIProductName": "uXB9wJUa",
    "specId": null,
    "specContent": null,
    "specTitle": null,
    "snapshotExists": false,
    "snapshotModified": null,
    "modified": 1729989250000,
    "anonAllowed": true,
    "imageUrl": null,
    "snapshotState": null,
    "requireCallbackUrl": false,
    "categoryIds": [],
    "specFormat": null,
    "specModified": null,
    "snapshotOutdated": null,
    "snapshotSourceMissing": false,
    "graphqlSchema": null,
    "graphqlEndpointUrl": null,
    "graphqlSchemaDisplayName": null,
    "grpcFileName": null,
    "grpcZipContent": null
  },
  "code": null,
  "request_id": "738172002",
  "error_code": null
}

Gérer l'instantané du document

Une fois l'API publiée, vous pouvez à tout moment effectuer un nouvel instantané d'un document OpenAPI ou GraphQL pour mettre à jour la documentation de référence qui est publiée sur votre portail.

Pour gérer l'instantané du document:

  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. Vérifiez l'état de l'instantané. S'il est obsolète, le message suivant s'affiche : Icône et message indiquant que l&#39;instantané est obsolète
  5. Cliquez sur icône de modification.
  6. Effectuez l'une des tâches suivantes :
    • Pour actualiser un instantané d'un document OpenAPI obsolète, cliquez sur Actualiser l'instantané.
    • Pour modifier le document utilisé pour générer la documentation de l'API, sous "Documentation API", cliquez sur Sélectionner un document, puis sélectionnez le nouveau document.
  7. Cliquez sur Enregistrer.

Publier ou annuler la publication d'une API sur votre portail

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

Utilisez l'UI ou la commande curl pour publier ou annuler la publication d'une API sur votre portail.

UI

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

  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 Icône de modification 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 de mise à jour:

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

Pour modifier l'API :

  1. Renvoyer les valeurs actuelles:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
-H "Authorization: Bearer ACCESS_TOKEN"

  2. Utilisez l'appel 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, il est écrasé par la valeur par défaut.

    curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/  ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
 -H "Authorization: Bearer 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
}

Consultez la section Gérer la version du document pour obtenir un exemple détaillé des étapes, des variables et de la charge utile renvoyée.

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

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

  • Public (visible par tout le monde)
  • Utilisateurs authentifiés
  • Audiences sélectionnées (si vous êtes inscrit à la version bêta de la fonctionnalité de gestion des audiences)

Utilisez l'UI ou la commande curl pour gérer la visibilité d'une API dans votre portail:

UI

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

  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 Icône de modification Modifier.

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

    • 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.
    Sélectionnez l'une des options suivantes :
    • 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 l'interface utilisateur pour gérer les 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. Renvoyer les valeurs actuelles:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer ACCESS_TOKEN"

  2. Utilisez l'appel 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://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer 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
     }'

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.

Utilisez l'UI ou la commande curl pour gérer l'URL de rappel d'une API:

UI

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

  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 Icône de modification Modifier.
  5. Sous Détails de l'API, cochez ou décochez la case Exiger des développeurs qu'ils spécifient une URL de rappel.
  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. Renvoyer les valeurs actuelles:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer ACCESS_TOKEN"

  2. Utilisez l'appel 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://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer 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
     }'

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.

Utilisez l'UI ou la commande curl pour gérer l'image d'une fiche API:

UI

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

  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 Icône de modification Modifier.

  5. Sous Détails de l'API :

    • Cliquez sur Sélectionner une image pour spécifier ou importer une image si aucune image n'est sélectionnée.
    • Cliquez sur Modifier l'image pour spécifier ou importer 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. Renvoyer les valeurs actuelles:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer ACCESS_TOKEN"

  2. Utilisez l'appel 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://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer 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
     }'

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 taguer une API à l'aide de catégories, procédez de l'une des manières suivantes :

  • Gérez les catégories auxquelles une API est taguée lors de la modification de l'API, comme décrit ci-dessous.
  • Gérez les API taguées à une catégorie lorsque vous modifiez la catégorie.

Utilisez l'UI ou la commande curl pour ajouter un tag de catégorie à une API:

UI

Pour taguer une API à des catégories lors de sa modification, procédez comme suit :

  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 Icône de modification 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. Renvoyer les valeurs actuelles:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer ACCESS_TOKEN"

  2. Utilisez l'appel 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://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer 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
     }'

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

Utilisez l'UI ou la commande curl pour modifier l'intitulé et la description:

UI

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

  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 Icône de modification 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. Renvoyer les valeurs actuelles:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer ACCESS_TOKEN"

  2. Utilisez l'appel 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://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer 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
     }'

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 de votre portail

Utilisez l'UI ou la commande curl pour supprimer une API de votre portail:

UI

Pour supprimer une API de votre portail, :

  1. Accédez au catalogue d'API.
  2. Sélectionnez les API, si elles ne sont pas déjà sélectionnées.
  3. Placez votre curseur sur l'API de la liste pour afficher le menu d'actions.
  4. Cliquez sur Icône Supprimer Supprimer.

curl

Pour supprimer une API de votre portail:

curl -X DELETE "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
    -H "Authorization: Bearer ACCESS_TOKEN"

Remplacez les éléments suivants :

  • ORG_NAME par le nom de l'organisation. Exemple :my-org
  • SITE_ID avec 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. 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.
  • ACCESS_TOKEN avec le jeton d'authentification utilisé pour accéder à l'API Apigee Edge. Pour en savoir plus sur l'authentification et les jetons, consultez la section Authentifier l'accès à l'API Edge.

Charge utile de la réponse :

{
  "status": "success",
  "message": "Apidoc deleted",
  "data": {
  },
  "code": null,
  "request_id": "1790036484",
  "error_code": null
}

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

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

UI

  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. Vérifiez l'état de l'instantané. S'il est obsolète, le message suivant s'affiche : Icône et message indiquant que l&#39;instantané est obsolète
  5. Cliquez sur Modifier.
  6. Effectuez l'une des tâches suivantes :
    • Pour actualiser un instantané d'un document OpenAPI obsolète, cliquez sur Actualiser l'instantané.
    • Pour modifier le document utilisé pour générer la documentation de l'API, sous "Documentation API", cliquez sur Sélectionner un document, puis sélectionnez le nouveau document.
  7. Dans le volet Documentation de l'API, sélectionnez l'une des options suivantes :
    • Document OpenAPI
    • Schéma GraphQL
  8. Cliquez sur Sélectionner un document, puis sélectionnez la dernière version du document.
  9. Pour GraphQL, spécifiez l'URL du point de terminaison.
  10. Cliquez sur Enregistrer.

La documentation de référence de l'API est affichée à partir du document et ajoutée à la page de référence de l'API. L'état de l'instantané passe à "Actuel" :

Icône et message indiquant que l&#39;instantané est actuel

curl

Pour mettre à jour le contenu de la documentation OpenAPI ou GraphQL:

OpenAPI

curl -X PATCH "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer 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. Exemple :my-org
  • SITE_ID avec 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. 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://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
  -H "Authorization: Bearer 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. Exemple :my-org
  • SITE_ID avec 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. 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": "ApiDocDocumentation updated",
"data": {
  "oasDocumentation": null,
  "graphqlDocumentation": {
    "schema": {
      "displayName": "schema.docs.graphql",
      "contents": ""
    },
    "endpointUri": "https://demo.google.com/graphql"
  }
},
"code": null,
"request_id": "640336173",
"error_code": null
}

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

Pour télécharger la documentation de l'API:

UI

curl

Pour télécharger la documentation de l'API à l'aide de get documentation:

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer ACCESS_TOKEN"

Remplacez les éléments suivants :

  • ORG_NAME par le nom de l'organisation. Exemple :my-org
  • SITE_ID avec 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. 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": "ApiDocDocumentation returned",
  "data": {
    "oasDocumentation": {
      "spec": {
        "displayName": "mock",
        "contents": "b3BlbmFwaTogMy4wLjAKaW5mbzoKICBkZXNjcmlw ..."
      },
      "format": "YAML"
    },
    "graphqlDocumentation": null
  },
  "code": null,
  "request_id": "269996898",
  "error_code": null
}

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 :

UI

  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 effacer le contenu existant, utilisez l'API Update:

curl -X PATCH "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{}'

Remplacez les éléments suivants :

  • ORG_NAME par le nom de l'organisation. Exemple :my-org
  • SITE_ID avec 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. 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": "ApiDocDocumentation updated",
  "data": {
    "oasDocumentation": null,
    "graphqlDocumentation": null
  },
  "code": null,
  "request_id": "304329676",
  "error_code": null
}

Gérer les catégories utilisées pour découvrir les API associées

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.

Parcourir les catégories

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

UI

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

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

curl

Pour lister les catégories:

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer ACCESS_TOKEN"

Remplacez les éléments suivants :

  • ORG_NAME par le nom de l'organisation. Exemple :my-org
  • SITE_ID avec 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. Exemple : my-org-myportal.
  • ACCESS_TOKEN avec le jeton d'authentification utilisé pour accéder à l'API Apigee Edge. Pour en savoir plus sur l'authentification et les jetons, consultez la section Authentifier l'accès à l'API Edge.

Charge utile de la réponse :

{
  "status": "success",
  "message": "all ApiCategory items returned",
  "data": [
    {
      "id": "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
      "siteId": "my-org-myportal",
      "name": "My Category"
    },
    {
      "id": "61c1014c-89c9-40e6-be3c-69cca3505620",
      "siteId": "my-org-myportal",
      "name": "test2"
    }
  ],
  "code": null,
  "request_id": "1263510680",
  "error_code": null
}

Où :

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

Ajouter une catégorie

Ajoutez une catégorie de l'une des manières suivantes :

  • Saisissez le nom d'une catégorie lorsque vous ajoutez une API au portail.
  • Ajoutez manuellement une catégorie comme décrit ci-dessous

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.

Pour ajouter une catégorie, utilisez l'interface utilisateur ou la commande curl:

UI

Pour ajouter manuellement une catégorie, procédez comme suit :

  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:

curl -X POST "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

Remplacez les éléments suivants :

  • ORG_NAME par le nom de l'organisation. Exemple :my-org
  • SITE_ID avec 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. Exemple : my-org-myportal.
  • ACCESS_TOKEN avec le jeton d'authentification utilisé pour accéder à l'API Apigee Edge. Pour en savoir plus sur l'authentification et les jetons, consultez la section Authentifier l'accès à l'API Edge.
  • CATEGORY_NAME par le nom de la catégorie. Par exemple, demo-backend.

Charge utile de la réponse :

{
  "status": "success",
  "message": "API category created",
  "data": {
    "id": "61de810e-b48b-4cc1-8f22-959038aadcce",
    "siteId": "my-org-myportal",
    "name": "demo-backend"
  },
  "code": null,
  "request_id": "363146927",
  "error_code": null
}

Modifier une catégorie

Utilisez l'interface utilisateur ou la commande curl pour modifier une catégorie:

UI

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

  1. Accédez à la page "Catégories".
  2. Cliquez sur Modifier.
  3. Modifiez le nom de la catégorie.
  4. Ajoutez ou supprimez des tags d'API.
  5. Cliquez sur Enregistrer.

curl

Pour modifier une catégorie:

curl -X PATCH "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID"  \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

Remplacez les éléments suivants :

  • ORG_NAME par le nom de l'organisation. Exemple :my-org
  • SITE_ID avec 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. Exemple : my-org-myportal.
  • 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.
  • ACCESS_TOKEN avec le jeton d'authentification utilisé pour accéder à l'API Apigee Edge. Pour en savoir plus sur l'authentification et les jetons, consultez la section Authentifier l'accès à l'API Edge.
  • CATEGORY_NAME par le nom de la catégorie. Par exemple, demo-backend.

Charge utile de la réponse :

{
  "status": "success",
  "message": "ApiCategory updated",
  "data": {
    "id": "61de810e-b48b-4cc1-8f22-959038aadcce",
    "siteId": "my-org-myportal",
    "name": "demo-backend-test"
  },
  "code": null,
  "request_id": "1976875617",
  "error_code": null
}

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, utilisez l'interface utilisateur ou la commande curl:

UI

Pour supprimer une catégorie :

  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:

curl -X DELETE "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json"

Remplacez les éléments suivants :

  • ORG_NAME par le nom de l'organisation. Exemple :my-org
  • SITE_ID avec 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. 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.
  • ACCESS_TOKEN avec le jeton d'authentification utilisé pour accéder à l'API Apigee Edge. Pour en savoir plus sur l'authentification et les jetons, consultez la section Authentifier l'accès à l'API Edge.

Charge utile de la réponse :

{
  "status": "success",
  "message": "ApiCategory deleted",
  "data": {
  },
  "code": null,
  "request_id": "2032819627",
  "error_code": null
}

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 : L'en-tête "Access-Control-Allow-Origin" contient plusieurs valeurs "*, *", mais une seule est autorisée

Lorsque vous utilisez Essayer cette API, il est possible que vous receviez le message d'erreur suivant si l'en-tête Access-Control-Allow-Origin existe déjà:

The Access-Control-Allow-Origin header contains multiple values '*, *', but only one is allowed.

Pour corriger cette erreur, modifiez la règle AssignMessage pour utiliser <Set> afin de définir les en-têtes CORS au lieu de <Add>, comme indiqué dans l'extrait ci-dessous. Pour en savoir plus, consultez Erreur CORS : l'en-tête contient plusieurs valeurs "*, *", mais une seule est autorisée.

<AssignMessage async="false" continueOnError="false" enabled="true" name="add-cors">
    <DisplayName>Add CORS</DisplayName>
    <FaultRules/>
    <Properties/>
    <Set>
        <Headers>
            <Header name="Access-Control-Allow-Origin">{request.header.origin}</Header>
            <Header name="Access-Control-Allow-Headers">origin, x-requested-with, accept, content-type, authorization</Header>
            <Header name="Access-Control-Max-Age">3628800</Header>
            <Header name="Access-Control-Allow-Methods">GET, PUT, POST, DELETE</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

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 :

Access to XMLHttpRequest ... has been blocked by CORS policy: Request header 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'OAuth2

La règle OAuthV2 d'Apigee renvoie une réponse de jeton contenant 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.