Bonnes pratiques pour la conception et le développement de proxys d'API

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

Ce document vise à fournir un ensemble de normes et de bonnes pratiques pour le développement à l'aide d'Apigee Edge. Les sujets abordés ici incluent la conception, le codage, l'utilisation des règles, la surveillance et le débogage. Ces informations ont été recueillies par les développeurs travaillant avec Apigee pour la mise en œuvre de programmes d'API efficaces. Il s'agit d'un document évolutif, mis à jour de temps en temps.

En plus des consignes présentées ici, le post destiné à la communauté Antimodèles Apigee Edge peut également vous être utile.

Normes de développement

Commentaires et documentation

  • Fournissez des commentaires internes dans les configurations ProxyEndpoint et TargetEndpoint. Les commentaires améliorent la lisibilité d'un flux, en particulier lorsque les noms des fichiers de règles ne sont pas suffisamment descriptifs pour exprimer la fonctionnalité sous-jacente du flux.
  • Proposez des commentaires utiles. Évitez les commentaires évidents.
  • Veillez à la cohérence des mises en retrait, des espacements, des alignements verticaux, etc.

Codage de type framework

Le codage de type framework consiste à stocker des ressources de proxy d'API dans votre propre système de contrôle des versions pour les réutiliser dans des environnements de développement locaux. Par exemple, pour réutiliser une règle, stockez-la dans le contrôle des sources afin que les développeurs puissent la synchroniser et l'utiliser dans leurs propres environnements de développement de proxy.

  • Pour activer le stockage DRY ("don't repeat yourself"), si possible, les configurations et scripts de règles doivent mettre en œuvre des fonctions spécialisées et réutilisables. Par exemple, une règle dédiée pour extraire les paramètres de requête des messages de requête peut s'appeler ExtractVariables.ExtractRequestParameters. Une règle dédiée pour injecter les en-têtes CORS peut s'appeler AssignMessage.SetCORSHeaders. Ces règles peuvent ensuite être stockées dans votre système de contrôle de source et ajoutées à chaque proxy d'API devant extraire des paramètres ou définir des en-têtes CORS, sans que vous ayez à créer des configurations redondantes (et donc moins faciles à gérer).
  • Nettoyez les règles et les ressources inutilisées (JavaScript, Java, Excel, etc.) par les proxys d'API, en particulier des ressources volumineuses pouvant ralentir les procédures d'importation et de déploiement.

Conventions d'attribution de noms

  • L'attribut name de la règle et le nom du fichier XML de la règle doivent être identiques.
  • L'attribut name des règles Script et ServiceCallout doivent être identiques au nom du fichier de ressources.
  • DisplayName doit décrire précisément la fonction de la règle à une personne qui n'a jamais travaillé avec ce proxy d'API auparavant.
  • Nommez les règles selon leur fonction. Apigee vous recommande d'établir une convention de dénomination cohérente pour vos règles. Par exemple, utilisez des préfixes courts suivis d'une séquence de mots descriptifs séparés par des tirets. Par exemple, AM-xxx pour les règles AssignMessage. Consultez également l'outil apigeelint.
  • Utilisez les extensions appropriées pour les fichiers de ressources : .js pour JavaScript, .py pour Python et .jar pour les fichiers JAR Java.
  • Les noms des variables doivent être cohérents. Si vous choisissez un style, tel que "camelCase" ou "under_score", utilisez-le sur l'ensemble du proxy d'API.
  • Si possible, utilisez des préfixes de variable afin d'organiser les variables en fonction de leur finalité, par exemple Consumer.username et Consumer.password.

Développement d'un proxy d'API

Éléments à prendre en compte lors de la conception initiale

  • Pour obtenir des conseils sur la conception d'une API RESTful, téléchargez l'e-book Web API Design: The Missing Link.
  • Exploitez autant que possible les règles et fonctionnalités d'Apigee Edge pour créer des proxys d'API. Évitez de coder la logique de proxy dans les ressources JavaScript, Java ou Python.
  • Créez vos flux de manière organisée. Plusieurs flux, comportant chacun une seule condition, sont préférables à plusieurs rattachements conditionnels au même PreFlow et au même Postflow.
  • Pour ce faire, créez un proxy d'API par défaut avec un chemin d'accès de base ProxyEndpoint /. Cela peut être utilisé pour rediriger les requêtes d'API de base vers un site de développement, pour renvoyer une réponse personnalisée ou pour effectuer une autre action plus utile que de renvoyer la valeur par défaut messaging.adaptors.http.flow.ApplicationNotFound.
  • Utilisez les ressources TargetServer pour dissocier les configurations TargetEndpoint des URL concrètes, en autorisant la promotion dans l'ensemble des environnements.
    Consultez la section Équilibrage de charge sur les serveurs de backend.
  • Si vous avez plusieurs règles de routage, créez-en une servant de "valeur par défaut", c'est-à-dire sans condition. Assurez-vous que la règle de routage par défaut est définie en dernier dans la liste des routes conditionnelles. Les règles de routage sont évaluées de haut en bas dans ProxyEndpoint.
    Consultez la documentation de référence sur la configuration des proxys d'API.
  • Taille d'un groupe de proxys d'API : les groupes de proxys d'API ne peuvent excéder 15 Mo. Dans Apigee Edge pour Private Cloud, vous pouvez modifier la limite de taille en modifiant la propriété thrift_framed_transport_size_in_mb aux emplacements suivants : cassandra.yaml (dans Cassandra) et conf/apigee/management-server/repository.properties.
  • Gestion des versions d'API: pour obtenir des informations et des recommandations d'Apigee concernant la gestion des versions d'API, consultez la section "Gestion des versions" de l'e-book Web API Design: The Missing Link.

Activer CORS

Avant de publier vos API, vous devez activer CORS sur vos proxys d'API pour pouvoir accepter les requêtes d'origine croisée côté client.

CORS (Cross-Origin Resource Sharing) est un mécanisme standard qui permet aux appels XMLHttpRequest (XHR) exécutés sur une page Web d'interagir avec des ressources 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. Par exemple, si vous effectuez un appel XHR à l'API Twitter à partir de code JavaScript exécuté dans votre navigateur, l'appel échoue. En effet, le domaine qui diffuse la page vers votre navigateur est différent du domaine diffusant l'API Twitter. CORS offre une solution à ce problème en autorisant des serveurs à "accepter" explicitement le partage de ressources entre origines multiples.

Pour en savoir plus sur l'activation de CORS sur vos proxys d'API avant la publication des API, consultez la section Ajouter la prise en charge de CORS à un proxy d'API.

Taille de la charge utile des messages

Pour éviter les problèmes de mémoire dans Edge, la taille de la charge utile des messages est limitée à 10 Mo. Le dépassement de ce quota entraîne une erreur protocol.http.TooBigBody.

Ce problème est également abordé dans ce post destiné à la communauté Apigee.

Voici les stratégies recommandées pour gérer des tailles de messages importantes dans Edge:

  • Diffuser un flux de requêtes et de réponses. Notez que lorsque vous diffusez un flux, les règles n'ont plus accès au contenu du message. Consultez la section Diffusion de flux de requêtes et de réponses.
  • Dans Edge pour Private Cloud version 4.15.07 et antérieure, modifiez le fichier http.properties du processeur de messages pour augmenter la limite dans le paramètre HTTPResponse.body.buffer.limit. Veillez à effectuer des tests avant de déployer le changement en production.
  • Dans Edge pour Private Cloud version 4.16.01 et ultérieure, les requêtes avec une charge utile doivent inclure l'en-tête Content-Length ou, en cas de streaming, l'en-tête "Transfer-Encoding: chunked". Pour une requête POST envoyée à un proxy d'API avec une charge utile vide, vous devez définir la valeur Content-Length sur 0.
  • Dans Edge pour Private Cloud version 4.16.01 et ultérieure, définissez les propriétés suivantes dans /opt/apigee/router.properties ou message-processor.properties pour modifier les limites. Pour en savoir plus, consultez Définir la limite de taille de message sur le routeur ou le processeur de messages.

    La valeur par défaut des deux propriétés est "10m", ce qui correspond à 10 Mo :
    • conf_http_HTTPRequest.body.buffer.limit
    • conf_http_HTTPResponse.body.buffer.limit

Gestion des erreurs

  • Utilisez les règles FaultRules pour gérer les erreurs. (Les règles RaiseFault sont utilisées pour interrompre le flux de messages et déléguer le traitement au flux FaultRules.)
  • Dans le flux FaultRules, utilisez les règles AssignMessage pour créer la réponse à l'erreur, et non les règles RaiseFault. Exécutez les règles AssignMessage de manière conditionnelle en fonction du type d'erreur.
  • Incluez toujours un gestionnaire d'erreurs "catch-all" par défaut pour pouvoir mapper les erreurs générées par le système aux formats de réponse d'erreur définis par le client.
  • Si possible, faites en sorte que les réponses d'erreur soient toujours conformes aux formats standards disponibles dans votre entreprise ou votre projet.
  • Utilisez des messages d'erreur explicites et intelligibles, qui suggèrent une solution à la condition d'erreur.

Consultez la page Gérer les erreurs.

Pour connaître les bonnes pratiques dans ce domaine, consultez la page Concevoir des réponses d'erreur RESTful.

Persistance

Mappages clé-valeur

  • Utilisez des mappages clé-valeur uniquement pour des ensembles de données limités. Ceux-ci ne sont pas conçus pour stocker des données sur le long terme.
  • Tenez compte des performances lors de l'utilisation de mappages clé-valeur, car ces informations sont stockées dans la base de données Cassandra.

Consultez la section Règle des opérations de mappage clé-valeur.

Mise en cache des réponses

  • Ne remplissez pas le cache de réponse si la réponse n'est pas réussie ou si la requête n'est pas une requête GET. Les créations, les mises à jour et les suppressions ne doivent pas être mises en cache. <SkipCachePopulation>response.status.code != 200 or request.verb != "GET"</SkipCachePopulation>
  • Complétez le cache avec un seul type de contenu cohérent (par exemple, XML ou JSON). Après avoir récupéré une entrée responseCache, convertissez-la au type de contenu requis avec JSONtoXML ou XMLToJSON. Vous évitez ainsi de stocker le double, le triple ou plus encore de données.
  • Assurez-vous que la clé de cache est suffisante pour la mise en cache. Dans de nombreux cas, la valeur request.querystring peut être utilisée comme identifiant unique.
  • N'incluez pas la clé API (client_id) dans la clé de cache, sauf si elle est explicitement requise. Le plus souvent, les API sécurisées uniquement par une clé renvoient les mêmes données à tous les clients pour une requête particulière. Il est inefficace de stocker la même valeur pour un certain nombre d'entrées en fonction de la clé API.
  • Définissez des intervalles d'expiration pour le cache afin d'éviter les opérations de lecture intensive.
  • Dans la mesure du possible, essayez de faire en sorte que la règle de cache de réponse qui remplit le cache soit exécutée lors de la réponse PostFlow le plus tard possible. En d'autres termes, faites en sorte qu'elle s'exécute après les étapes de traduction et de médiation, y compris la médiation et la conversion basées sur JavaScript entre JSON et XML. En mettant en cache les données ayant fait l'objet d'une médiation, vous évitez les coûts de performances liés à l'exécution de l'étape de médiation chaque fois que vous récupérez des données mises en cache.

    Notez que vous pouvez également mettre en cache des données non résolues si la médiation génère une réponse différente selon les requêtes.

  • La règle de cache de réponse de recherche d'entrée de cache doit intervenir dans la requête PreFlow de ProxyEndpoint. Évitez de mettre en œuvre trop de logique autre que la génération de clé de cache avant de renvoyer une entrée de cache. Sinon, les avantages de la mise en cache sont minimes.
  • En général, vous devez toujours faire en sorte que la consultation du cache de réponse soit aussi rapprochée que possible de la demande du client. Inversement, vous devez faire en sorte que le remplissage du cache de réponse soit aussi rapproché que possible de la réponse du client.
  • Lorsque vous utilisez plusieurs règles de cache de réponses différentes dans un proxy, suivez les consignes ci-dessous pour que chacune se comporte discrètement :
    • Exécutez chaque règle en fonction de conditions qui s'excluent mutuellement. Cela permet de garantir l'exécution d'une seule règle de cache de réponse.
    • Définissez des ressources de cache différentes pour chaque règle de cache de réponse. Spécifiez la ressource de cache dans l'élément <CacheResource> de la règle.

Consultez la page concernant la règle de cache de réponses.

Règle et code personnalisé

Règle ou code personnalisé ?

  • Utilisez avant tout les règles intégrées (si possible). Les règles Apigee sont renforcées, optimisées et compatibles. Par exemple, utilisez les règles standards AssignMessage et ExtractVariables au lieu de JavaScript (si possible) pour créer des charges utiles, extraire des informations des charges utiles (XPath, JSONPath), etc.
  • JavaScript est préférable à Python et Java. Toutefois, si les performances sont l'exigence principale, Java doit être utilisé via JavaScript.

JavaScript

  • Utilisez JavaScript s'il est plus intuitif que les règles Apigee (par exemple, lorsque vous définissez target.url pour de nombreuses combinaisons d'URI différentes).
  • Analyse complexe de charge utile telle que l'itération d'un objet JSON et le codage/décodage en Base64.
  • La règle JavaScript possède une durée limite. Les boucles infinies sont donc bloquées.
  • Toujours utiliser les étapes JavaScript et placer les fichiers dans le dossier de ressources jsc. Les règles de type JavaScript précompilent le code au moment du déploiement.

Consultez la page Programmation des proxys d'API avec JavaScript.

Java

  • Utilisez Java si les performances sont de prioritaires ou si la logique ne peut pas être mise en œuvre via JavaScript.
  • Incluez les fichiers source Java dans le suivi du code source.

Pour en savoir plus sur l'utilisation de Java dans les proxys d'API, consultez les pages Convertir la réponse en majuscules avec un appel Java et règle d'appel Java.

Python

  • N'utilisez pas Python à moins d'y être absolument obligé. Les scripts Python peuvent introduire des goulots d'étranglement affectant les performances des exécutions simples, car ils sont interprétés au moment de l'exécution.

Appels de scripts (Java, JavaScript, Python)

  • Utilisez un try/catch global ou équivalent.
  • Générez des exceptions pertinentes et interceptez-les correctement pour les utiliser dans les réponses d'erreur.
  • Générez et interceptez les exceptions de manière anticipée. N'utilisez pas de try/catch global pour gérer toutes les exceptions.
  • Effectuez des vérifications NULL et non définies, si nécessaire. Par exemple, lorsque vous récupérez des variables de flux facultatives.
  • Évitez d'effectuer des requêtes HTTP/S dans un appel de script. Utilisez plutôt la règle ServiceCallout d'Apigee, car elle gère les connexions sans interruption.

JavaScript

  • JavaScript sur la plate-forme d'API est compatible avec XML via E4X.

Consultez la page Modèle d'objet JavaScript.

Java

  • Lorsque vous accédez aux charges utiles des messages, essayez d'utiliser context.getMessage() plutôt que context.getResponseMessage ou context.getRequestMessage. Cela garantit que le code peut récupérer la charge utile dans les flux de requête et de réponse.
  • Importez des bibliothèques dans l'organisation ou l'environnement Apigee Edge, et ne les incluez pas dans le fichier JAR. Cela réduit la taille du groupe et permet aux autres fichiers JAR d'accéder au même dépôt de bibliothèque.
  • Importez des fichiers JAR à l'aide de l'API de ressources Apigee au lieu de les inclure dans le dossier des ressources des proxys d'API. Cela réduit les temps de déploiement et permettra aux fichiers JAR d'être référencés par plusieurs proxys d'API. Autre avantage : l'isolation du chargeur de classe.
  • N'utilisez pas Java pour le traitement des ressources (par exemple, la création et la gestion de pools de threads).

Pour en savoir plus, consultez Convertir la réponse en majuscules avec un appel Java.

Python

  • Générez des exceptions pertinentes et interceptez-les correctement pour les utiliser dans les réponses d'erreur d'Apigee

Consultez la règle de script Python.

ServiceCallouts

  • Il existe de nombreux cas d'utilisation valides du chaînage de proxys, qui consiste à utiliser un appel de service dans un proxy d'API pour appeler un autre proxy d'API. Si vous utilisez le chaînage de proxy, évitez les appels récursifs en "boucle infinie" au sein du même proxy d'API.

    Si vous connectez des proxys au sein d'une même organisation et d'un même environnement, assurez-vous de consulter la page Chaîner des proxys d'API pour en savoir plus sur la mise en œuvre d'une connexion locale permettant d'éviter une surcharge inutile du réseau.

  • Créez un message de requête ServiceCallout à l'aide de la règle AssignMessage et attribuez l'objet de la requête à une variable de message. (Cela inclut la définition de la charge utile de la requête, du chemin et de la méthode.)
  • L'URL configurée dans la règle requiert la spécification du protocole, ce qui signifie que la partie protocole de l'URL, https:// par exemple, ne peut être spécifiée par une variable. De plus, vous devez utiliser des variables distinctes pour la partie domaine de l'URL et pour le reste de l'URL. Par exemple : https://{domain}/{path}
  • Stockez l'objet de réponse d'un ServiceCallout dans une variable de message séparée. Vous pouvez alors analyser la variable de message et préserver la charge utile du message original pour l'utiliser dans d'autres règles.

Consultez la page Règle ServiceCallout.

Accéder aux entités

Règle AccessEntity

  • Pour de meilleures performances, recherchez les applications par uuid plutôt que par leur nom.

Consultez la page Règle AccessEntity.

Logging

  • Utilisez une règle syslog commune entre les groupes et dans un même groupe. Cela conserve un format de journalisation cohérent.

Consultez la page Règle MessageLogging.

Surveillance

Les clients cloud ne sont pas tenus de vérifier les composants individuels d'Apigee Edge (routeurs, processeurs de messages, etc.). L'équipe de développement internationale d'Apigee contrôle minutieusement tous les composants et vérifie l'état des API à la demande du client.

Apigee Analytics

Analytics peut assurer un suivi non critique des API en mesurant les pourcentages d'erreur.

Consultez la page Tableaux de bord Analytics.

Trace

L'outil de traçage de l'interface utilisateur de gestion des API Edge est utile pour déboguer les problèmes d'exécution des API lors de leur développement ou de leur exploitation en production.

Consultez la section Utiliser l'outil Trace.

Sécurité