Qu’est-ce qui rend OData si spécial ?
OData est une forme d'API REST, à la différence qu'elle a standardisé certaines fonctionnalités que les API REST n'ont pas. Pour commencer, OData prend en charge l'interrogation et le filtrage des requêtes elles-mêmes. OData crée également une piste d'audit fonctionnelle des modifications apportées aux données de votre application une fois implémentées. Lorsque vous essayez de résumer OData en une phrase : OData est une bonne pratique pour la création d'API REST, vous pouvez donc mieux exploiter les capacités de REST.
Vous trouverez ci-dessous un extrait de la page Web officielle OData.org où ils expliquent dans leurs propres mots ce qu'est OData :
« OData (Open Data Protocol) est un Approuvé ISO/CEI, Norme OASIS qui définit un ensemble de bonnes pratiques pour la création et l'utilisation d'API RESTful. OData vous aide à vous concentrer sur votre logique métier tout en créant des API RESTful sans avoir à vous soucier des différentes approches pour définir les en-têtes de requête et de réponse, les codes d'état, les méthodes HTTP, les conventions d'URL, les types de média, les formats de charge utile, les options de requête, etc. OData fournit également des conseils pour le suivi des modifications, la définition de fonctions/actions pour les procédures réutilisables et l'envoi de requêtes asynchrones/par lots. » — OData.org
Les ensembles de données OData peuvent être utilisés dans d’autres outils tels que Microsoft Excel et Power BI. Mendix supports Version OData 3, qui renvoie des données au format Atom XML, et Version OData 4, qui renvoie des données au format JSON et XML, selon le format demandé par le client.
Comment utilisons-nous OData dans Mendix?
In Mendix Avec Studio Pro, il est relativement facile de créer une API OData. Comme pour les services REST classiques, Studio Pro nous offre également la possibilité de générer une API directement à partir de notre modèle de domaine.
Une fois que nous avons créé un service OData, nous pouvons le publier sur Datahub simplement en déployant votre application dans un environnement cloud. Datahub est un catalogue de métadonnées ouvert, ce qui signifie essentiellement que vous pouvez partager des données entre vos Mendix applications une fois que vous avez enregistré le service OData sur Datahub. Cela aide également à la découverte et à la compréhension des API elles-mêmes.
Cependant, vous n'avez pas besoin d'utiliser Datahub pour utiliser OData dans Mendix, vous pouvez toujours le faire manuellement en téléchargeant les contrats $metadata pour les API elles-mêmes.
Une fois qu'il a été enregistré dans Datahub, l'intégration des données dans un autre Mendix l'application est aussi simple que de glisser-déposer l'entité distante (le service OData enregistré Datahub) dans votre modèle de domaine.
Au moment où j'écris ces lignes, Mendix vient de publier Studio Pro 9.17.0 qui présente de nouvelles améliorations étonnantes sur l'utilisation d'OData dans Mendix, ci-dessous est un extrait des notes de version 9.17.0:
Nous avons étendu les fonctionnalités OData dans Studio Pro, vous permettant de Envelopper des services, des API et des bases de données avec OData et le rendre plus facile à construire des connecteurs qui accèdent à des données externes. Les services OData peuvent alors être facilement découverts et utilisés dans le Catalogue du Data Hub. Les nouvelles fonctionnalités incluent la possibilité de [publier des entités non persistantes en tant que ressources OData](](https://docs.mendix.com/refguide/wrap-services-odata/#npe-published-odata), et à utiliser des microflux pour définir comment les ressources doivent être récupérées et stockées. Nous fournissons également un OpenAPI contrat pour facilement tester les ressources OData publiées.
Accéder à la documentation de l'API
Une fonctionnalité très puissante d'OData dans Mendix c'est qu'une fois que votre application est déployée ou exécutée localement, vous pouvez accéder à une documentation API pour vos services OData publiés à l'adresse l'URL de base de votre application + '/odata-doc/'.
Par exemple, l'emplacement du document sur une application locale exécutée sur le port 8080 serait :
https://localhost:8080/odata-doc/
Pour OData, le contrat OData $metadata et le contrat OpenAPI sont tous deux disponibles ici. Vous pouvez même utiliser la page OpenAPI pour tester les appels OData vers votre API.
OData en pratique
Cette section suivante sera un guide pratique sur la façon de publier une API OData dans votre Mendix Application, enregistrez ce service sur Datahub, puis consommez les données en tant qu'entité distante dans un autre Mendix .
Le scénario:
Imaginez que vous avez créé un e-commerce Mendix application. Dans votre application, vous disposez d'une entité contenant des commandes qui sont transmises aux employés de l'entrepôt pour terminer la commande et l'expédier au client. Lorsque les employés approvisionnent l'entrepôt, ils répertorient l'emplacement de stockage de chaque produit dans une feuille Excel. Actuellement, l'entrepôt imprime les commandes à partir d'une feuille Excel et recherche l'emplacement de stockage des articles dans son propre document Excel, ce qui est inefficace et ralentit l'ensemble du processus.
Votre application existante contient des informations client sensibles, vous ne souhaitez donc pas les exposer au personnel externe de l'entrepôt. Vous décidez de créer une application distincte qui permet aux employés de visualiser les commandes et les articles nécessaires pour les terminer, et décidez de partager les informations à l'aide d'OData et Mendix Centre de données.
Générer l'API OData à partir de votre modèle de domaine
Dans notre application de commerce électronique, nous avons les entités suivantes dans le modèle de domaine : $Order et $Orderline qui ont une association 1 à plusieurs.
Lorsque nous faisons un clic droit sur une entité (dans notre cas $Orders), cela nous donne l'option « Exposer en tant que ressource OData »
Lorsque nous cliquons ici, il nous demande où nous souhaitons créer la nouvelle API dans notre projet et quel nom nous souhaitons donner à la ressource.
Nous sommes alors automatiquement amenés à visualiser la ressource générée et à modifier ses propriétés. Nous pouvons les laisser telles quelles, car nous avons uniquement besoin que les employés de l'entrepôt consultent les informations de la commande, et ils ne devraient pas être autorisés à modifier les détails de la commande.
Bien que nous n’utilisions pas ces fonctionnalités, je pense que je dois souligner que Datahub n’est plus en lecture seule — vous pouvez désormais insérer de nouveaux enregistrements, mettre à jour et supprimer en plus de lire les données.
Nous pouvons ensuite ajouter l'entité $Orderline à la ressource. Pour ce faire, nous pouvons cliquer sur le bouton Ajouter sous Entités, rechercher $orderline et cliquer sur OK.
Une fois que nous faisons Sstudio Pro reconnaît que ces entités sont liées et vous demande si vous souhaitez publier l'association entre elles, cliquez sur Oui.
Une fois que nous l'aurons fait, vous remarquerez quelques erreurs dans la console, comme ceci :
Nous devons nous assurer que $Itemname et $OrderNumber ne peuvent pas être vides car ils sont utilisés comme clés pour l'API.
Et nous devons ajouter une règle de validation d'unicité à $ItemName, ce que nous pouvons faire dans le modèle de domaine
Publication de la ressource OData sur Datahub
Cette partie est vraiment facile, il suffit de déployer votre application dans un environnement cloud ! N'importe qui pourra travailler, du cloud gratuit à toute autre solution d'hébergement qui Mendix offre.
Chaque API OData que vous déployez dans le Mendix Le cloud sera enregistré automatiquement, ce qui signifie que votre API sera également mise à jour automatiquement. Cela garantit que la documentation est toujours à jour et toujours adaptée à l'environnement auquel vous souhaitez vous connecter. Le catalogue vous indiquera quelle version est en cours d'exécution en test, en acceptation ou en production, car nous offrons la possibilité d'utiliser le contrôle de version sémantique sur l'API.
Si vous n'exécutez pas vos applications dans le Mendix Cloud vous permet d'utiliser les API du catalogue pour enregistrer automatiquement vos déploiements dans vos propres processus CICD. Vous pouvez également le faire manuellement dans le catalogue Data Hub.
Pour cet exemple, je vais simplement déployer sur le Mendix Cloud gratuit. Une fois votre application déployée, vous recevrez un e-mail de Mendix Datahub vous informe que votre nouvelle ressource OData a été automatiquement enregistrée dans le catalogue.
Consommer votre entité externe à partir de Datahub
Dans notre nouvelle application (celle pour les employés de l'entrepôt), nous avons une table appelée Produit
Nous souhaitons inclure les entités $Order et $Orderline que nous avons publiées sur Datahub ici dans ce module.
Dans le modèle de domaine, accédez au volet Datahub sur le côté droit et recherchez le nom de votre service enregistré (si vous avez déployé sur le cloud gratuit, vous devrez activer les environnements de développement sur le filtre)
Une fois que vous avez localisé votre service, faites simplement glisser les deux entités dans le modèle de domaine de votre nouvelle application et Studio Pro s'occupera du reste.
Vous êtes maintenant libre d'utiliser les données $order et $orderline comme vous le souhaitez dans votre application ! Bravo !
Quelques éléments à prendre en compte
Il est important de se rappeler qui doit pouvoir accéder aux informations de votre application. Lorsque vous utilisez des entités distantes dans une application, assurez-vous de vérifier la sécurité de votre application.