La plupart des API que vous rencontrez suivent un ensemble de règles connues sous le nom de Representational State Transfer ou REST en abrégé. Dans ce blog, je me concentrerai sur les API REST et sur leur fonctionnement Mendix.

Représentatif quoi maintenant ?

En termes simples, REST est un ensemble de « règles » ou de protocoles qui régissent le transfert de données. Lorsqu'une API suit ces règles, on l'appelle une API RESTful. Le terme REST a été inventé par Roy Fielding dans sa thèse de doctorat « Architectural Styles and the Design of Network-based Software Architectures » publiée en 2000. Ne vous inquiétez pas, vous n'aurez pas besoin de lire sa thèse pour comprendre les API RESTful : elles sont depuis devenues le moyen de facto de transférer des données entre les systèmes sur le Web d'aujourd'hui.

Alors, quelles sont ces règles ? La réponse courte est qu'elles varient selon les différentes API, mais certaines normes universellement acceptées contribuent à créer une API RESTful :

• Il organise les entités ou les ressources dans des URI uniques. URI signifie Uniform Resource Identifier (identifiant de ressource uniforme). Ils sont constitués de deux parties : un emplacement réseau et la ressource à laquelle vous essayez d'accéder. L'emplacement réseau est généralement l'URL d'un site Web et la ressource est une table de données que contient le site Web.
• Il est apatride. Cela signifie que vous pouvez appeler n'importe quelle API dans n'importe quel ordre, à condition de lui fournir les détails corrects dont elle a besoin. Cela fonctionne également bien pour les applications hautes performances, car le serveur n'a pas besoin de stocker les données de session du client.
• Il utilise Méthodes HTTPLes API RESTful sont disponibles dans différents types ou méthodes HTTP. La façon dont vous souhaitez interagir avec les données définit le type de méthode à utiliser.ÉCONOMISEZ Récupère les données, POSTEZ Crée des données, PATCH Mise à jour des données, EFFACER Détruit ou efface les données. Il y en a d'autres mais ce sont les *principaux*)
• La charge utile des données est formatée à l'aide de JSON or XML. La plupart des API REST formatent les données en charges utiles JSON ou XML. Certains autres formats incluent HTML, balisage, images et documents (lorsqu'une API prend en charge plusieurs formats de charges utiles, vous pouvez spécifier le format que vous souhaitez renvoyer à l'aide de l'option «Accepter" En-tête)

Si vous souhaitez en savoir plus sur l'histoire et les normes de REST, vous pouvez en savoir plus sur Wikipédia.

Consommer VS Publier

Dans le développement d'API, il existe une différence entre publier une API pour que d'autres l'utilisent et en consommer une soi-même. Mendix vous permet de faire les deux, vous pouvez consommer des API REST d'autres systèmes et publier les vôtres, le tout dans la même application. Certaines applications appellent même leurs propres services exposés, une partie de leur architecture.

Comme mon article précédent portait sur la consommation, dans ce blog Je parlerai de la publication des API REST in Mendix.

Il convient de mentionner ici que Mendix prend également en charge les API OData prêt à l'emploi, qui offre de nombreux avantages dans certains scénarios et dispose de filtres puissants comme ignorer, filtrer, trier par et sélectionner. Cependant, cet article concerne les API REST standard et je préférerais aborder OData dans mon prochain blog, car il s'agit d'un sujet vaste et j'aimerais le couvrir en détail.

Création d'un service REST exposé

La meilleure façon d'apprendre quelque chose est de le faire. Cette section sera donc un guide pratique sur la façon de publier une API REST. Pour travailler avec un cas d'utilisation simple, je vais vous montrer comment créer une collection simple d'API pour interagir avec une application de catalogue de films simple que j'ai déjà créée.

Comme vous pouvez le voir, l'application n'est qu'une page d'accueil affichant une liste de titres de films et un lien vers la page IMDB de ce film. Remplissez-la de données pour avoir quelque chose avec lequel interagir.

Si nous voulons exposer les données d’une entité dans notre modèle de domaine, nous pouvons simplement sélectionner l’entité, cliquer dessus avec le bouton droit de la souris et choisir « Exposer en tant que ressource REST »

Il vous demandera un service dans votre projet, mais vous pouvez choisir d'en créer un nouveau dans n'importe quel module de votre projet. Pour cet exemple, j'ai appelé le mien Movielist.

Vous devrez ensuite choisir un attribut clé. Cela n'est nécessaire que si vous souhaitez interagir avec des données spécifiques et utiliser des méthodes HTTP telles que GET par clé, Patch et Delete

Une fois que vous avez cliqué sur OK, Studio Pro s'occupera du reste et générera tous les mappages et la logique nécessaires pour servir votre entité en tant qu'API REST.

À ce stade, vous pouvez exécuter votre projet localement et interagir avec l'API via Postman ou un autre logiciel de test d'API.

Une fois votre application en cours d'exécution, vos nouveaux services seront accessibles (sur votre machine de développement locale) et vous pourrez voir un résumé de toutes les API publiées de votre application sur {Your_app_URL/api-doc/} qui, dans mon exemple, est : https://localhost:8080/api-doc/

Tester l'API avec Postman

Une fois que votre application est en cours d'exécution et que vous avez Facteur installé et ouvert sur la même machine, vous pouvez ouvrir les détails de la méthode GET qui a été générée pour nous par Studio Pro, en double-cliquant dessus.

Vous remarquerez qu'il existe un champ appelé emplacement d'exemple. Il s'agit d'un exemple car il utilise l'hôte local et le port d'exécution de la copie locale de votre application. Cela fonctionnera bien pour Postman, nous pouvons donc copier cet URI et l'utiliser ici.

Dans Postman, créez une nouvelle demande et collez l'URI dans le champ URI de la demande et cliquez sur envoyer.

Vous devriez voir les résultats renvoyés dans la fenêtre ci-dessous, formatés en XML. Notez que nous recevons également un champ d'état qui est 200 OK. Cela signifie que la demande a été traitée avec succès.

Le faire soi-même

Cela semble simple, mais que faire si je souhaite avoir plus de contrôle sur ce que fait le service ? Eh bien, vous n'avez pas besoin de compter sur Studio Pro pour le générer à votre place. Vous pouvez également créer une API entièrement à partir de zéro et dicter chaque détail à votre guise.

J'ai mentionné ci-dessus que les services générés automatiquement que nous avons créés renverront les données au format XML. Cela convient à la plupart des scénarios, mais que se passe-t-il si vous souhaitez plutôt renvoyer les résultats au format JSON ?

Nous pouvons ouvrir le microflow qui gère la logique de ce point de terminaison. Dans ce cas, il s'appelle « Movies_Get_All »

À l'heure actuelle, le microflux récupère simplement tous les enregistrements et les renvoie. La conversion en XML est gérée par le mappage d'exportation connecté au service REST appelé « Movies_Export ».

Pour modifier le type de retour en JSON nous pouvons utiliser l'en-tête « Accepter » avec la valeur «Application/JSON" comme je l'ai mentionné plus haut.

Sans réexécuter votre application, testez-la à nouveau dans Postman sans modifier aucun détail autre que l'ajout de l'en-tête « Accepter » — « Application/JSON ».

Si tout se passe bien, vous recevrez la charge utile au format JSON. Notez que le temps de réponse du service a diminué de près de 400 ms (millisecondes), ce qui représente une amélioration considérable des temps de réponse de l'API. Cela est dû au fait que JSON a été spécifiquement conçu pour le transfert de données. Vous pouvez affiner les services pour des temps de réponse encore plus rapides en utilisant les meilleures pratiques d'optimisation telles que application d'index pour accélérer les temps de récupération des bases de données.

Construire à partir de zéro

Vous pouvez aller plus loin et créer tous les composants de l'API à partir de zéro. Nous pouvons essayer cela maintenant en créant une nouvelle ressource pour ce service exposé, qui accueillera spécialement les utilisateurs.

Pour commencer, cliquez sur « Ajouter » sous les ressources du service exposé, donnez un nom à la nouvelle ressource (j’ai appelé la mienne « hellothere ») et cliquez sur « OK ».

Ensuite, nous devons créer une opération pour cette ressource. Une fois la nouvelle ressource sélectionnée, cliquez sur « Ajouter » sous « Opérations ».

Nous laisserons la méthode GET et ne modifierons pas le chemin de l'opération. Nous devons uniquement fournir un microflux pour gérer la logique. Cliquez sur « Sélectionner », sélectionnez l'emplacement où vous souhaitez le flux et cliquez sur « Nouveau ». J'ai utilisé le nom du microflux généré automatiquement, « GetHelloThere ».

Ouvrez le flux et double-cliquez sur le point de terminaison du microflux afin que nous puissions spécifier la charge utile des données sous forme de chaîne JSON personnalisée.

'{''salutation'':''https://www.youtube.com/watch?v=eaEMSKzqGAg”}'

Notez les citations autour des paires clé-valeur JSON de salutation et du lien Youtube. Ce ne sont pas des guillemets doubles mais plutôt 2 guillemets simples ouvrant et fermant. Ceci permet d'échapper à la chaîne car Studio Pro interprète normalement les guillemets comme une rupture dans la variable de chaîne, cela indique à Studio Pro d'inclure des citations dans la réponse.

Nous pouvons maintenant réexécuter notre application et tester le nouveau service dans Postman, et si tout va bien, nous devrions voir notre charge utile personnalisée renvoyée avec un 200 OK statut.

Tout ensemble!

Vous savez maintenant tout ce dont vous avez besoin pour commencer à créer vos propres API REST en utilisant Mendix. Si vous souhaitez en savoir plus, comme ajouter des fonctionnalités de sécurité, d'authentification ou des en-têtes personnalisés à votre service, rendez-vous sur academy.mendix.com et découvrez-en plus. Ne manquez pas mon prochain article dans lequel je plonge dans le monde d'OData.