Fast API Development en utilisant InterSystems Open Exchange Tools

Dans cet article, je partagerai le thème que nous avons présenté lors du Global Summit 2023, dans la salle Tech Exchange. Moi et @Rochael Ribeiro

Lors de cette présentation, nous abordons les sujets suivants :

• Outils Open Exchange pour des API rapides
• Spécification de l'Open API
• Développement d'API traditionnel ou Fast
• API composite (interopérabilité)
• Approche Spec-First ou Api-First
• Gouvernance et surveillance des API
• Démo (vidéo)

Outils Exchange ouverts pour des API Fast

Comme nous parlons de développement rapide d'API modernes (Rest / json), nous utiliserons deux outils Intersystems Open Exchange :

Le premier est un framework de développement rapide d’API que nous détaillerons dans cet article.

https://openexchange.intersystems.com/package/IRIS-apiPub

Le second consiste à utiliser Swagger comme interface utilisateur pour la spécification et la documentation des API REST développées sur la plateforme IRIS, ainsi que leur utilisation/exécution. La base de son fonctionnement est la norme de spécification Open API (OAS), décrite ci-dessous :

 https://openexchange.intersystems.com/package/iris-web-swagger-ui

 

Qu'est-ce que l'Open API Specification (OAS)?

Il s'agit d'un standard utilisé dans le monde entier pour définir, documenter et utiliser des API. Dans la plupart des cas, les API sont conçues avant même leur mise en œuvre. J'en parlerai davantage dans les prochains sujets.

Il est important car il définit et documente les API REST pour leur utilisation, à la fois du côté du fournisseur et du consommateur. Mais ce schéma sert aussi à accélérer les tests et les appels API dans les outils (REST APIs Clients) du marché, comme Swagger, Postman, Insomnia, etc…

 

Méthode traditionnelle pour publier une API à l'aide d'IRIS

Imaginez que nous devions créer et publier une API REST à partir d'une méthode IRIS existante (image ci-dessous).

De manière traditionnelle :

1 : Nous devons réfléchir à la façon dont les consommateurs l’appelleront. Par exemple : quel chemin et quel verbe seront utilisés et quelle sera la réponse. Que ce soit dans un objet JSON ou sous forme de texte brut.

2 : Créer une nouvelle méthode dans une classe %CSP.REST qui gérera la requête http pour l'appeler.

3 : Gérer la réponse de la méthode à la réponse http prévue pour l'utilisateur final.

4 : Réfléchir à la manière dont nous allons fournir le code de réussite et à la manière dont nous allons gérer les exceptions.

5 : Tracer l’itinéraire de notre nouvelle méthode.

6 : Fournir la documentation de l'API à l'utilisateur final. Nous allons probablement créer le contenu OAS manuellement.

7 : Et si, par exemple, nous avons une charge utile de requête ou de réponse (objet), le temps de mise en œuvre augmentera, car cela doit également être documenté dans OAS.

 

Comment pouvons-nous être plus rapides ?

En marquant simplement la méthode IRIS avec l'attribut [WebMethod]. Quoi qu'il en soit, le framework se chargera de sa publication, en utilisant le standard OAS 3.x.

Pourquoi la norme OAS 3.x est-elle si importante ?

Parce qu'elle documente également en détail toutes les propriétés des charges utiles d'entrée et de sortie.

De cette manière, tous les outils clients REST sur le marché peuvent se coupler instantanément aux API, comme Insomnia, Postman, Swagger, etc. et fournir un exemple de contenu pour les appeler facilement.

En utilisant Swagger, nous allons déjà visualiser notre API (image ci-dessus) et l'appeler. Ceci est également très utile pour les tests.

Personnalisation des API

Mais que se passe-t-il si je dois personnaliser mon API ?

Par exemple : au lieu du nom de la méthode, je souhaite que le chemin soit autre chose. Et je veux que les paramètres d'entrée soient dans le chemin, pas comme un paramètre de requête.

Nous définissons une notation spécifique en plus de la méthode, où nous pouvons compléter les méta-informations que la méthode elle-même ne fournit pas.

Dans cet exemple, nous définissons un autre chemin pour notre API et complétons les informations permettant à l'utilisateur final d'avoir une expérience plus conviviale.

Carte de projection pour l'API Rest

Ce framework prend en charge de nombreux types de paramètres.

Dans cette carte, nous pouvons mettre en évidence les types complexes (les objets). Ils seront automatiquement exposés en tant que charge utile JSON et chaque propriété sera correctement documentée (OAS) pour l'utilisateur final.

 

Interopérabilité (API composites)

En prenant en charge des types complexes, vous pouvez également exposer les services d'interopérabilité.

Il s'agit d'un scénario favorable pour créer des API composites, qui utilisent l'orchestration de plusieurs composants externes (sortants).

Cela signifie que les objets ou messages utilisés comme requête ou réponse seront automatiquement publiés et lus par des outils comme swagger.

Et c'est un excellent moyen de tester les composants d'interopérabilité, car généralement un modèle de charge utile est déjà chargé afin que l'utilisateur sache quelles propriétés l'API utilise.

Le développeur peut d’abord se concentrer sur les tests, puis façonner l’API grâce à la personnalisation.

Approche Spec-first ou Api-first

Un autre concept largement utilisé aujourd’hui consiste à définir l’API avant même sa mise en œuvre.

Avec ce framework, il est possible d'importer une Open Api Spec. Il crée automatiquement la structure des méthodes (spécifications), en ne manquant que leur implémentation.

Gouvernance et surveillance des API

Pour la gouvernance d'Api, il est également recommandé d'utiliser IAM.

En plus de disposer de plusieurs plugins, IAM peut rapidement se coupler aux API via la norme OAS.

apiPub propose un traçage supplémentaire pour les API (voir vidéo de démonstration)

Demo

https://www.youtube.com/embed/IdJ1PqmhH3c
[Ceci est un lien intégré, mais vous ne pouvez pas consulter le contenu intégré directement sur le site car vous avez refusé les cookies nécessaires pour y accéder. Pour afficher le contenu intégré, vous devez accepter tous les cookies dans vos Paramètres des cookies]

Téléchargement et documentation

Intersystems Open Exchange: https://openexchange.intersystems.com/?search=apiPub

Documentation complète: https://github.com/devecchijr/apiPub