Pourquoi REST ?

Bien que les API ou les plugins d'application soient disponibles dans de nombreuses variétés et normes, je vais parler de mon préféré : les services REST. Vous vous demandez peut-être : « Pourquoi REST ? ». La réponse est simple, c'est plus simple que SOAP. Il existe également d'autres raisons : REST prend en charge plus de formats de données que SOAP, qui ne prend en charge que XML. Une autre raison importante pour laquelle je pense que REST est le MEILLEUR est qu'il va de pair avec JSON.

JSON (JavaScript Object Notation) offre une analyse des données plus rapide en général, ce qui signifie une meilleure prise en charge des navigateurs avec ce format de données léger. Enfin, la consommation d'API REST dans Mendix ne nécessite pas l'installation de bibliothèques ou de fichiers client pour que votre application fonctionne.

Quelle API j'utilise ?

L'API Google Cloud propose une suite complète des meilleurs services de Google, tous divisés en méthodes consommables, dont beaucoup sont entièrement gratuites. Cependant, avant de pouvoir interagir avec l'une de ces API, votre requête devra s'authentifier avec un jeton OAuth. Google utilise OAuth 2.0 comme méthode d'authentification de facto pour la plupart de ses API. Cela signifie que pour qu'un utilisateur puisse utiliser une API Google, il devra d'abord appeler l'API API d'identité Google (Pour les applications côté serveur), afin de pouvoir effectuer les appels ultérieurs aux services de Google.

En d’autres termes, l’obtention d’un jeton est la première étape de la mise en œuvre de nombreuses API de Google et constitue un bon point de départ pour quelqu’un qui souhaite se lancer dans le développement d’API.

Pré-requis :

Avant de commencer, ce blog suppose que vous avez activé une API Google pour un projet sur Google Cloud Platform, ainsi que terminé le Page d'informations d'identification OAuth et Écrans de consentement Oauth pour ce projet Google. En particulier, vous devrez configurer des URL de redirection pour que votre application pointe vers votre hôte local ou votre application Web déployée et vous devrez disposer d'un ID client et d'un secret client fournis par Google après avoir configuré le client OAuth de votre application.

Un mot sur les méthodes REST

Dans cet exemple, j'utilise une méthode POST pour appeler l'API d'identité de Google, mais qu'est-ce que cela signifie ? Dans REST, il y a 5 méthodes que vous devez connaître :

• POSTEZ — Ceci est utilisé pour créer de nouveaux enregistrements
• ÉCONOMISEZ — Cela renvoie un enregistrement ou une liste d’enregistrements
• PUT — Utilisé pour mettre à jour ou remplacer un enregistrement
• PATCH — Utilisé pour mettre à jour ou modifier un enregistrement
• EFFACER — Supprimer ou alléger l'enregistrement

Il existe d'autres méthodes que je connais, mais je ne les ai jamais rencontrées dans mon travail, si vous êtes intéressé, il existe un bon résumé des méthodes ici.

Un plan général pour l'intégration des services REST

Selon la méthode que vous utilisez et l'API que vous consommez, les étapes réelles pour terminer une intégration peuvent varier. Par exemple, une requête GET n'a pas de corps de requête et utilise à la place des chaînes de requête. Mais en général, voici les étapes à suivre pour consommer un service REST dans Mendix Studio Pro :

1. Définir votre position

• Également connu sous le nom de points de terminaison ou URI, il s'agit de l'emplacement où le service est hébergé

2. Choisissez votre méthode HTTP

• Un choix entre les méthodes mentionnées ci-dessus, généralement la documentation de l'API vous indiquera laquelle sélectionner.

3. Authentification

• Cela peut être OAUTH, une clé API ou ne pas être requis du tout.

4. En-têtes HTTP

• Les en-têtes peuvent jouer différents rôles, chaque service est capable d'avoir des en-têtes uniques, vous devrez vous référer à la documentation de l'API que vous essayez de consommer.

Pour définir le format de la réponse, nous pouvons utiliser l'en-tête «Type de contenu" et lui donner de la valeur "Application/JSON" pour le format JSON ou "Application/XML" pour XML. D'autres options existent telles que 'Application/x-www-form-urlencoded', que nous utiliserons dans ce tutoriel (consultez cet article sur Stack Overflow pour un excellent résumé de tous les types de contenu).

5. Créer la demande

• Pour la plupart des méthodes, vous devrez fournir un corps de requête, généralement au format JSON. Pour les méthodes GET, nous utilisons normalement des chaînes de requête ajoutées à la fin de l'emplacement pour transmettre des paramètres, normalement identifiés par un « ? » à la fin de l'emplacement, également appelé URI.

6. Gérez la réponse

• Il existe plusieurs options ici, depuis le stockage de la réponse dans une variable de chaîne, ou l'application d'un mappage d'importation qui mappera les données à votre modèle de domaine, la meilleure option ici changera au cas par cas, mais dans la plupart des cas, vous devriez choisir d'appliquer un mappage d'importation.

Comment fonctionne Google Identity ?

Avant de commencer, une explication rapide de la manière dont Google implémente OAuth 2.0 pour les applications côté serveur.

Documentation de Google l'explique en 5 étapes que je vous résume ici : Utilisation d'OAuth 2.0 pour les applications de serveur Web | Google Identity | Google Developers.

Étape 1 : Définir les paramètres d’autorisation

Cela signifie que nous devons créer une URL dans notre Mendix application, qui détaille à quoi notre application souhaite accéder, au nom de l'utilisateur, à partir des services de Google.

À l'étape 2, l'utilisateur est redirigé vers cette URL Google pour approuver l'accès au compte Google de l'utilisateur, puis il sera redirigé vers votre Mendix application, ainsi qu'un code d'accès que nous utiliserons pour autoriser notre demande de jeton.

Les valeurs importantes ici sont :

• URI redirigée (Doit rediriger vers l'URL de votre application),
• Scopes (Autorisations pour les API Google, par exemple mail/drive/traduction, etc., cliquez sur ici (pour une liste de toutes les portées des API Google)
• identité du client (ID client fourni par Google après l'enregistrement de votre application sous OAuth)
• État (Une valeur utilisée par l'application pour maintenir l'état, un identifiant que vous pouvez utiliser pour récupérer la demande correcte ultérieurement)

Voici un exemple de ce à quoi cette URL pourrait ressembler :

https://accounts.google.com/o/oauth2/v2/auth?portée=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-translation&type_d'accès=hors ligne&inclure_les_portées_accordées=vrai&type_réponse=Code&Etat= 123 &redirect_uri=https://localhost:8080/link/googleredirect?code=&client_id=281413935351-jh5hs5chgf9n84eeqhpodrfq6oir2qnk.apps.googleusercontent.com

Étape 2 : Redirection vers le serveur OAuth 2.0 de Google

Rediriger l'utilisateur vers l'URL que vous avez créée à l'étape 1 (j'ai utilisé l'action Javascript Ouvrir l'URL disponible dans Nanoflows)

Étape 3 : Google demande le consentement de l'utilisateur

Google demande à l'utilisateur de se connecter/sélectionner son compte, puis d'approuver l'accès demandé par votre application.

Étape 4 : gérer la réponse du serveur OAuth 2.0

Une fois que l'utilisateur a vérifié la demande sur son compte, Google redirigera l'utilisateur vers le paramètre URI de redirection que nous avons fourni à l'étape 1. Il s'agit de l'URL de votre application, mais dans mon cas, j'ai utilisé le Lien profond module pour gérer la redirection. De cette façon, je pourrais accéder au code d'autorisation que Google inclut dans le lien. Voici un exemple de lien profond créé pour gérer cela :

https://localhost:8080/link/googleredirect?code=

Étape 5 : échanger le code d'autorisation contre des jetons d'actualisation et d'accès

Une fois que Google vous donne le Code d'accès, vous pouvez maintenant effectuer l'appel REST pour l'échanger contre un jeton officiel. Voici la requête et la réponse pour mon exemple

J'ai supprimé mon projet sur Google, après avoir publié ceci, ces requêtes ne fonctionneront pas telles quelles (Vous devrez utiliser votre propre identifiant client et votre secret client)

Demander le contenu de la requête POST à https://oauth2.googleapis.com/token?grant_type=authorization_code&client_id=281413935351-jh5hs5chgf9n84eeqhpodrfq6oir2qnk.apps.googleusercontent.com&client_secret=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&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Flink%2Fgoogleredirect%3FCode%3D 
Type de contenu HTTP/1.1 : application/x-www-form-urlencoded

code=4%2F0AdQt8qiGaCaJYgKgRpHKqXj8265JL72PfsKpusgctqYXhVwPxg5qn4EHU9iUGnMxMiHiqA

Contenu de la réponse à la requête POST à https://oauth2.googleapis.com/token?grant_type=authorization_code&client_id=281413935351-jh5hs5chgf9n84eeqhpodrfq6oir2qnk.apps.googleusercontent.com&client_secret=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&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Flink%2Fgoogleredirect%3FCode%3D
HTTP/1.1 200 OK Cache-Control : no-cache, no-store, max-age=0, must-revalidate Pragma : no-cache Date : lun. 01 août 2022 12:53:44 GMT Expire : lun. 01 janv. 1990 00:00:00 GMT Content-Type : application/json ; charset=utf-8 Vary : Origin Vary : X-Origin Vary : Referer Server : scaffolding on HTTPServer2 X-XSS-Protection : 0 X-Frame-Options : SAMEORIGIN X-Content-Type-Options : nosniff Alt-Svc : h3=”:443"; ma=2592000,h3–29=”:443"; ma=2592000,h3-Q050=”:443"; ma=2592000,h3-Q046=”:443"; ma=2592000,h3-Q043=”:443"; ma=2592000,quic=”:443"; ma=2592000; v=”46,43" Transfer-Encoding : fragmenté

{
 “access_token”: “ya29.A0AVA9y1tawnqK-42beGFAomiTqx8Zg0UUiedmIIPaAIraSas6VEO2D7NH5rInBPCUQK_7aghDiiTVrD_SnnQzOAtGq3XP2GQfWbpuZmDFjWfL0FSAw6JQU37mthQnRFsJvvqlgzTcryTdruKiOtcc63YrI8DvYUNnWUtBVEFTQVRBU0ZRRTY1ZHI4NjVOQUxhR2ppS0kyOVpINVZoYTJ4Zw0163”,
 “expires_in”: 3599,
 “scope”: “https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/cloud-translation", « token_type » : « Porteur » }

Maintenant que vous comprenez, espérons-le, l’architecture derrière tout cela, nous pouvons entrer dans les détails de l’appel de l’API Token.

Appel de l'API dans Mendix

Définir l'emplacement

Pour définir votre emplacement, accédez aux propriétés de votre action REST d'appel (dans un microflow) et cliquez sur Modifier. Vous pouvez définir l'emplacement ici en fournissant l'URI où se trouve l'API, entre guillemets, car il s'agit d'un Valeur de chaîne.

Cependant, il est recommandé de créer une constante d'application pour stocker ceci, afin de ne pas avoir à vous soucier des fautes de frappe ou des erreurs de copier-coller.

L'emplacement pour cela est https://oauth2.googleapis.com/tokenGardez à l’esprit que nous ajouterons une requête à la fin de l’emplacement.

Choix de la méthode HTTP

Comme mentionné ci-dessus, nous utilisons le Méthode POST pour cette intégration. J'ai sélectionné cette option car la documentation de Google indique que cela devrait être le cas dans leur exemple.

Ensuite, l'authentification

Pour nous assurer que nous sommes des utilisateurs enregistrés, nous devons envoyer à Google quelques détails dans notre demande. Nous devons fournir les ID client et secret client notre application a été émise par Google (en tant que champs de requête) et nous devons transmettre le Code d'accès accordé à l'utilisateur dans le corps de la demande.

De quels en-têtes avons-nous besoin ?

Pour cette requête, nous devons uniquement ajouter l'en-tête 'Type de contenu' et lui donner la valeur »application / x-www-form-urlencoded« Nous transmettons cela car cela indique à Google quel format votre demande utilise.

Vérifiez toujours la documentation fournie avant de supposer qu'il n'y en a pas, car le fait de ne pas inclure un en-tête obligatoire entraînera normalement une réponse 401 (mauvaise demande).

Construire notre requête

Comme nous devons transmettre certains paramètres pour notre requête dans l’URI, nous devons ajouter notre requête à l’emplacement de base des API.

L'emplacement de la base :

https://oauth2.googleapis.com/token

La chaîne de requête supplémentaire :

?type_octroi=code_autorisation&client_id=281413935351-jh5hs5chgf9n84eeqhpodrfq6oir2qnk.apps.googleusercontent.com&client_secret=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&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Flink%2Fgoogleredirect%3FCode%3

Voici une description détaillée de la signification de chaque champ, directement depuis Google :

N'oubliez pas d'encoder l'URL de votre requête avant d'en faire la demande.

Codage d'URL ? Qu'est-ce que c'est ?

S'il y a des caractères spéciaux ou des espaces dans la chaîne de requête, cela entraînera une erreur 401 (requête incorrecte). Il s'agit simplement d'un moyen de traduire ces caractères spéciaux en quelque chose qui est universellement accepté par les navigateurs. L'encodage d'URL est une fonction de chaîne dans Mendix, que vous pouvez appeler dans n'importe quel microflow ou nanoflow.

Vous pouvez maintenant tout ajouter ensemble et votre chaîne finale devrait ressembler à ceci

https://accounts.google.com/o/oauth2/v2/auth?portée=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-translation&type_d'accès=hors ligne&inclure_les_portées_accordées=vrai&type_réponse=Code&Etat= 1 &redirect_uri=https://localhost:8080/link/googleredirect?code=&client_id=281413935351-jh5hs5chgf9n84eeqhpodrfq6oir2qnk.apps.googleusercontent.com

Gardez à l’esprit que l’instruction de requête réelle contiendra vos informations d’identification et fournira le code d’accès et l’URL de redirection de l’utilisateur de votre application, elle sera donc différente de la mienne.

Définition du corps de la requête

Comme il s'agit d'une méthode de publication, nous devons fournir un corps de requête. Sous Requête, sélectionnez Modèle de demande personnalisé et fournir au corps :

code=VOTRE_CODE_D'ACCES_UTILISATEUR

Passons maintenant à la réponse

Mendix permettez nous de appliquer un mappage d'importation pour mapper les données de réponse dans votre modèle de domaine.

Pour cela, vous devez disposer d'un échantillon JSON de ce que devrait être la réponse. Dans sa documentation, Google nous donne cet exemple.

{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Porteur", "scope": "https://www.googleapis.com/auth/drive.metadata.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }

Dans Studio Pro, sélectionnez « Appliquer un mappage d’importation » sous l’onglet Réponse de l’activité REST d’appel.

Choisissez de créer un nouveau mappage d'importation à partir de la fenêtre qui apparaît et donnez un nom au mappage.

Une fois dans l'éditeur de mappage d'importation, cliquez sur «Sélectionner les éléments" dans le coin supérieur gauche de l'écran. Sélectionnez "Structure JSON" comme option pour cela.

Sélectionnez ou créer le mappage JSON, avec un nom approprié. Collez maintenant le JSON ci-dessus dans la zone de texte et cliquez sur « Actualiser ».

Cliquez sur « OK » pour fermer cette fenêtre. De retour sur l’écran « Sélectionner les éléments », cliquez sur « Développer tout », puis sur « Tout cocher », avant de cliquer sur « OK ».

Ensuite, dans le mappage d'importation, vous pouvez maintenant simplement cliquer sur « mapper automatiquement ». Studio Pro créera automatiquement toutes les entités et associations requises. Par défaut, celles-ci seront créées en tant qu'entités non persistantes (entités qui résident en mémoire et qui ne sont pas validées dans la base de données). Vous pouvez modifier ce mappage manuellement si nécessaire, mais la plupart du temps, il n'y en a pas et vous pouvez le laisser tel quel.

Vous pouvez désormais accéder et récupérer les données renvoyées par l'API dans votre microflow.

C'est à vous de décider ce que vous voulez faire des données une fois qu'elles sont accessibles dans votre application. Chaque service sera différent, aucune implémentation n'est identique.

Dans mon exemple, je stocke le jeton dans une entité persistante, qui est liée au compte utilisateur dans la base de données, mais dans une implémentation réelle, vous devez également envisager d'ajouter un cryptage.

C'est tout pour les amis

J'espère que vous avez trouvé cela utile, si vous souhaitez en savoir plus sur la façon d'implémenter les services REST dans Mendix, Consultez notre Documentation page pour plus d'informations, ou rendez-vous sur notre académie et commencer à apprendre.