Publier vos API

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X. En savoir plus

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 d'un instantané de votre document OpenAPI ou de votre schéma GraphQL pour permettre aux développeurs d'applications d'en savoir plus sur vos API. (Pour en savoir plus sur les instantanés, consultez la page Qu'est-ce qu'un instantané ?)

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

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.

Cliquez sur 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 plus, comme indiqué ci-dessous.

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.

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 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 Gérer l'URL de rappel pour 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 votre proxy d'API pour qu'il soit compatible avec la fonctionnalité "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 :

• Ajouter une compatibilité CORS à vos proxys d'API pour appliquer les requêtes multi-origines 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 à 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.

Explorer le catalogue d'API

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.

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

• Afficher les détails des API disponibles sur votre portail
• Ajouter une API à votre portail
• Modifiez une API sur votre portail en effectuant une ou plusieurs des tâches suivantes :
  • Gérer l'instantané d'un document associé à un produit d'API pour mettre à jour la documentation de référence de l'API
  • Publier ou annuler la publication d'une API sur votre portail
  • Gérer la visibilité d'une API dans votre portail :
  • Gérez l'URL de rappel pour une API
  • Gérer l'image pour une fiche d'API
  • Ajouter un tag de catégorie à une API
  • Modifier l'intitulé et la description d'une API
• Supprimer une API de votre portail
• Gérez les catégories utilisées pour identifier les API associées
• Identifier rapidement les spécifications obsolètes ou qui ont été supprimées du magasin de spécifications
• Identifiez rapidement les sites "orphelins" Les API dont le produit d'API associé a été supprimé d'Edge, puis recréer le produit d'API ou supprimer l'API de votre portail

Ajouter une API à votre portail

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 le signe +.

   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 ce paramètre ultérieurement, comme décrit dans 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	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 pouvez ajouter ou mettre à jour l'URL de rappel ultérieurement, comme décrit dans Gérer l'URL de rappel d'une API.
   Documentation de l'API	Pour utiliser un document OpenAPI : Sélectionnez OpenAPI document (Document OpenAPI). Cliquez sur Sélectionner un document. Effectuez l'une des opérations suivantes : Cliquez sur l'onglet Mes spécifications, puis sélectionnez une spécification dans le magasin de spécifications. Cliquez sur l'onglet Importer un fichier, puis importez un fichier. Cliquez sur l'onglet Importer à partir d'une URL, puis importez une spécification à partir d'une URL. Cliquez sur Sélectionner. Pour utiliser un schéma GraphQL : Sélectionnez Schéma GraphQL. Cliquez sur Select Document (Sélectionner un document). Accédez au schéma GraphQL et sélectionnez-le. Cliquez sur Sélectionner. Vous pouvez également sélectionner Aucune documentation et en ajouter une plus tard une fois l'API ajoutée, comme décrit dans 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. Audience sélectionnées pour sélectionner les audiences spécifiques que vous souhaitez autoriser à afficher l'API. Vous pouvez gérer la visibilité de l'audience ultérieurement, comme décrit dans 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 indiqué dans Gérer l'image d'une fiche API. Si vous spécifiez une image avec une URL externe, elle ne sera pas importée dans vos composants. En outre, le chargement de l'image dans le portail intégré dépend 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, procédez comme suit : 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.

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:
5. Cliquez sur .
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 sur l'API", cliquez sur Sélectionner un document, puis sélectionnez le nouveau document.
7. 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" :

Publier une API ou en annuler la publication sur votre portail

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

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)

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 .
5. Sous "Visibilité de l'API", sélectionnez l'une des options suivantes :

6. 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 :

   • 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.
   • Selected audiences (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.

7. Cliquez sur Envoyer.

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 :

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

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 :

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 .

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

Ajouter un tag de catégorie à une API

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.

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 .
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 ajouter des tags à l'API dans d'autres catégories.
7. Cliquez sur Enregistrer.

Modifier l'intitulé et la description

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 .
5. Modifiez les champs Intitulé et Description, si nécessaire.
6. Cliquez sur Enregistrer.

Supprimer une API de votre portail

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 .

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.

Explorer la page "Catégories"

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.

Comme le montre la figure précédente, la page des API vous permet de:

• Afficher les API et les catégories auxquelles elles sont taguées
• Ajouter une catégorie
• Modifier une catégorie
• Supprimer une catégorie
• Gérez les API publiées sur votre portail. Consultez la page Explorer le catalogue d'API.

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 manuellement une catégorie, procédez comme suit :

1. Accédez à la page "Catégories".
2. Cliquez sur le signe +.
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.

Modifier une catégorie

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

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

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 :

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 .
4. Modifiez le nom de la catégorie.
5. Ajouter ou supprimer des API
6. Cliquez sur Enregistrer.

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 cette API, si l'erreur TypeError: Failed to fetch est renvoyée, voici les causes et les résolutions possibles :

• Dans le cas d'erreurs de contenu mixte, l'erreur peut être due à un problème connu de l'interface utilisateur Swagger. Pour contourner le problème, vous pouvez spécifier HTTPS avant HTTP dans la définition de schemes de votre document OpenAPI. Exemple :

  schemes:
     - https
     - http
  

• Pour les erreurs de restriction Cross-Origin Resource Sharing (CORS), assurez-vous que CORS est compatible avec vos proxys d'API. CORS est un mécanisme standard qui active les requêtes multi-origines côté client. Consultez Configurer votre proxy d'API pour qu'il soit compatible avec la fonctionnalité Essayer cette API.

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 plus d'informations, consultez l'article de communauté pertinent.

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