Dans le contexte de l’architecture ou de la conception de système, la gestion des API fait généralement référence à un proxy inverse configurable et hautement performant qui permet de gérer l’accès des clients (externes, internes ou autres) à une API, un point de terminaison ou une méthode. Couramment utilisée avec les API RESTful, mais pas exclusivement, la gestion des API fournit une couche de gestion et de protection des requêtes afin qu’une requête entrante puisse être vérifiée, inspectée, modifiée et traitée, et que la réponse qui revient du système back-end puisse être modifiée ou prise en compte. Certaines organisations peuvent utiliser un bus de services d’entreprise pour atteindre des objectifs similaires. Un bus de services d’entreprise est un terme défini de manière flexible désignant une classe de technologies qui incluent des implications supplémentaires liées à ce composant, mais qui peuvent bénéficier du même ensemble de recommandations pour les services de gestion des API.
Voici quelques exemples de systèmes ou technologies de gestion des API :
Les modèles de gestion des API peuvent être utilisés pour fournir un proxy aux points de terminaison de service ArcGIS Enterprise, ArcGIS Online ou ArcGIS Location Platform, bien que cela puisse introduire des complications. Les clients d’ArcGIS Online et ArcGIS Enterprise, tels que les applications Web configurables ou ArcGIS Data Pipelines, peuvent se connecter aux services de gestion des API, s’ils sont correctement définis, et s’intégrer via cette connexion. ArcGIS Pro peut se connecter à des couches en proxy via la gestion des API, mais ce modèle peut présenter des complications techniques et doit être soigneusement testé.
| Fonctionnalité | ArcGIS Online | ArcGIS Enterprise | ArcGIS Location Platform | ArcGIS Pro |
|---|---|---|---|---|
| Gestion des API |
Prise en charge complète Prise en charge partielle
Le comportement de la gestion des API est différent de celui d’un proxy inverse traditionnel, qui transmet généralement un modèle entier de trafic HTTP à un serveur back-end. Par exemple :
<external-host>:443/server/rest/services/* » <internal-host>>:6443/arcgis/rest/services/*
La gestion des API implique souvent la sélection de chemins d’accès individuels aux URI d’API et de méthodes HTTP, comme un POST vers /routes/extract et un PATCH vers /routes/<routeid>. Cela signifie que chaque méthode ou modèle individuel doit être défini, mais aussi que chaque modèle peut avoir des règles, des comportements et des processus d’écoute ou des services back-end différents. Cette approche est souvent utilisée pour la création de nouvelles API ou de nouveaux systèmes, lorsqu’un ensemble existant de services Web n’existe pas, ou pour l’activation d’une architecture de type microservices où différents composants ou systèmes back-end sont responsables de la prise en charge de requêtes d’API distinctes. Dans certains cas, la gestion des API peut utiliser une définition d’API back-end telle qu’une spécification OpenAPI pour créer de nombreux points de terminaison ou méthodes front-end.
La gestion des API comprend également généralement un éventail d’autres options de traitement, qui manipulent le contenu de la requête, par exemple pour ajuster ou réécrire un chemin, ajouter ou modifier un en-tête, modifier la destination en fonction du contenu du corps POST, appliquer un filtrage à la requête (limitation du débit, blocage de certaines plages d’adresses IP ou exigence de clés d’API) ou opèrent sur la réponse pour offusquer les noms de serveur, supprimer les en-têtes de réponse ou ajouter une empreinte digitale ou un identifiant. Ces opérations sont définies dans la couche de gestion des API et s’appliquent à chaque requête lorsqu’elle est soumise et qu’une réponse est créée.
Tous ces modèles s’appliquent généralement aux technologies de bus de services d’entreprise, à quelques différences près. Les bus de services d’entreprise ont tendance à être plus axés sur la distribution synchrone de messages, c’est-à-dire qu’une modification dans une partie du système (par exemple ajout d’un nouvel enregistrement ou application d’une mise à jour) déclenche la transmission de cette modification au bus, qui transforme ensuite et transmet le message à d’autres systèmes pour les maintenir synchronisés. Dans un sens, la gestion des API s’apparente davantage à une méthodologie de requête et d’interrogation, où les bus de services d’entreprise introduisent souvent des engagements forts en matière de distribution de messages, des modèles de publication/abonnement ou d’autres approches similaires.
La gestion des API est utilisable dans de nombreux modèles différents avec ArcGIS. En règle générale, la gestion des API est surtout applicable aux cas d’utilisation dans lesquels elle est déployée devant des services basés sur ArcGIS Server, tels que des services de carte, d’entités ou de géotraitement, dans des scénarios où ces services doivent être exposés à un autre système d’entreprise, à un développeur ou à un client final à l’aide d’une application personnalisée.
Voici quelques éléments clés à prendre en compte pour l’utilisation de la gestion des API :
La gestion des API fonctionne généralement mieux en tant que modèle architectural avec les déploiements ArcGIS Server autonomes. La gestion de l’échange de jetons et de la validation requis pour un serveur fédéré dans le cadre d’un déploiement ArcGIS Enterprise est beaucoup plus complexe et nécessiterait une configuration avancée d’ArcGIS ou une configuration et une connaissance de la gestion des API pour gérer la diversité des requêtes d’authentification et des points de terminaison.
Les services REST d’ArcGIS accessibles via un système de gestion des API sont généralement disponibles de manière anonyme, avec une protection au niveau du réseau ou du pare-feu, et les requêtes émanant du service de gestion des API sont envoyées au back-end ArcGIS sans étape d’authentification supplémentaire. Bien qu’ArcGIS prenne en charge de nombreux modèles d’authentification, des noms d’utilisateur et mots de passe intégrés aux méthodes SAML et OIDC, un modèle de gestion des API suppose souvent que l’API principale soit accessible de manière anonyme aux demandes provenant du service de gestion des API.
La gestion des API doit généralement être utilisée pour exposer des services ou des points de terminaison spécifiques, et non des sites ArcGIS Server entiers. Si vous avez pour objectif d’exposer un site entier, il est préférable d’utiliser un proxy inverse traditionnel, davantage compatible avec un éventail de processus plus large.
ArcGIS fournit généralement des API REST avec des commentaires, ce qui signifie que le service de gestion des API doit prendre en charge des modèles génériques flexibles ou transmettre uniquement des chemins d’accès spécifiques. Cela est particulièrement vrai si l’objectif consiste à exposer le service au logiciel client ArcGIS, qui est conçu pour obtenir une API entièrement disponible, dont toutes les méthodes et ressources sont accessibles. Par exemple :
/arcgis/rest/services/ServiceName/MapServer/arcgis/rest/services/ServiceName/MapServer/exportImage/arcgis/rest/services/ServiceName/MapServer/0/query/arcgis/rest/services/ServiceName/MapServer/1/queryLa gestion des API est un moyen de plus en plus populaire de fournir des options d’intégration entre les systèmes d’entreprise. De nombreuses organisations investissent dans des stratégies ou les développent pour s’assurer que toutes les transactions internes utilisent comme broker un système de gestion des API, ou peuvent nécessiter l’utilisation de la gestion des API pour créer des services accessibles en externe. Dans le contexte de l’intégration de systèmes, les meilleures pratiques sont les suivantes :
Si l’objectif est d’appliquer l’authentification uniquement au niveau du service de gestion des API et de faire en sorte que toutes les activités des utilisateurs utilisent ce point de terminaison, les services ArcGIS définis comme back-ends doivent généralement être configurés pour être non sécurisés ou partagés avec tout le monde, avec un accès public ou organisationnel limité par une conception de réseau ou un pare-feu, l’accès étant autorisé uniquement à partir du service de gestion des API.
Tenez compte des URL de contexte Web et de la mise en œuvre d’en-têtes liés au proxy pour vous assurer que le composant ArcGIS Server derrière une gestion d’API reconnaît le proxy et renvoie des URL valides dans la mesure du possible.
Les liens renvoyés à partir d’une requête via le service de gestion des API doivent être inspectés et modifiés de manière à utiliser le nom d’hôte et le contexte appropriés pour les requêtes ultérieures. Les services de gestion des API peuvent souvent remplacer le contenu dans un corps de réponse, comme les URL renvoyées par ArcGIS, ce qui peut être utile pour remplacer les réponses back-end. Par exemple, une requête de service d’impression asynchrone renvoie une URL finale à la sortie PDF résultante, qui sera demandée par un utilisateur. Cette URL peut faire référence à un nom d’hôte interne et le contenu peut être réécrit dans le système de gestion des API.
Les points de terminaison auxquels les modèles de gestion des API sont appliqués, tels que les points de terminaison de géocodage ou de calcul d’itinéraire, peuvent être plus complexes à intégrer dans les interfaces standard d’ArcGIS. Par exemple, un service de géocodage géré par Azure API Management, avec une clé d’abonnement requise, peut ne pas fonctionner parfaitement comme un service de géocodage standard configuré pour une organisation ArcGIS Online. Consultez la section suivante pour en savoir plus.
Lorsque vous utilisez des services de gestion des API et que vous dépannez les erreurs du client, comparez une requête envoyée par un client via la gestion des API à une requête envoyée directement au service back-end, en examinant attentivement les en-têtes et URL HTTP pour identifier les différences pertinentes.
Par définition, la gestion des API n’inclut pas de couche d’authentification, mais de nombreuses organisations souhaitent appliquer l’authentification à leurs points de terminaison de gestion des API, à des fins de validation des utilisateurs et de gestion des autorisations. Les méthodes d’authentification courantes de gestion des API incluent l’utilisation d’une clé ou d’un abonnement d’API, ainsi que l’intégration des méthodes d’authentification basées sur OAuth à un fournisseur d’identités existant. Chacun de ces modèles peut créer des défis pour les processus d’intégration ArcGIS.
N’oubliez pas que les méthodes d’authentification client basées sur la gestion des API peuvent ne pas être compatibles avec les clients ArcGIS standards. Si, par exemple, le système de gestion des API exige l’authentification basée sur l’en-tête, que ce soit à l’aide d’un en-tête spécifique au service ou d’un en-tête Bearer authorization, les clients ArcGIS standards ne pourront pas ajouter cet en-tête de manière dynamique aux requêtes de prise en charge de l’accès à ce service. De même, les clés d’API peuvent être une couche d’authentification commune ajoutée via une interface de gestion des API, mais les développeurs d’applications doivent être conscients de cette exigence et avoir la possibilité de l’ajouter aux requêtes afin d’intégrer ces services dans une application. Divers SDK ArcGIS et modèles d’inscription de service peuvent prendre en charge ce type de modèle d’authentification de clé d’abonnement ou de clé d’API. Il est cependant nécessaire de les tester minutieusement avant de supposer qu’un modèle d’authentification convient.
L’authentification basée sur OAuth pour la gestion des API présente d’autres défis. Lors du développement d’une application personnalisée à l’aide d’un SDK pris en charge, il peut être relativement simple de fournir une redirection initiale vers le service OAuth, de renvoyer un jeton ou un code, et d’utiliser celui-ci pour l’ajouter à d’autres requêtes dans cette session. Toutefois, lors de l’utilisation d’une application ArcGIS prête à l’emploi, cette configuration est beaucoup plus difficile à utiliser, car ces clients s’attendent à accéder directement aux services géographiques d’ArcGIS, sans étapes d’authentification supplémentaires qui ne sont pas gérées par ArcGIS.
Généralement, l’utilisation de clés d’API ou d’abonnement constitue le chemin d’intégration le plus efficace dans ce contexte, avec les recommandations suivantes :
Les clés d’API ou d’abonnement doivent prendre en charge l’utilisation en tant que paramètres de requête d’URL. L’authentification basée sur l’en-tête peut être prise en charge pour certains processus, tels qu’une application personnalisée basée sur le SDK Esri Maps ou une intégration basée sur Python mais, pour la plupart des interfaces existantes, l’utilisation d’un en-tête d’authentification non ArcGIS n’est pas possible pour le moment.
Les clés d’API peuvent être ajoutées à un élément de contenu créé dans les versions récentes d’ArcGIS Online ou d’ArcGIS Enterprise, soit en tant que paramètres personnalisés fournis lors de la création de l’élément, soit être directement ajoutées à l’URL inscrite avec l’élément. Testez ces options avec soin pour déterminer si elles offrent un accès suffisant au contenu demandé.
Lorsque vous utilisez des services protégés par des clés d’API dans ArcGIS Pro, le processus Ajouter des données à partir d’un chemin prend également en charge l’utilisation de paramètres personnalisés.