API Simplicité pour external Frontend integration

Bonjour,
Je me permets de vous écrire, car je travaille actuellement sur la mise en forme et mise en page de notre application afin de la rendre un peu plus accessible à un public moins avertis et expert. L’idée est donc de se défaire des layouts proposés par Simplicité, pour arriver sur qqch de plus conventionnel, sur une charte graphique que nous sommes entrain de définir et mettre en place, avec une expérience utilisateur retravaillée.

Pour cela, je m’étais initialement dirigé sur un redesign en interne de l’application Simplicité : appliqué un template sur l’affichage actuel. Mais si mes souvenirs sont bons, je sais qu’il n’est possible de modifier que le contenu même de la page, pas la présentation des menus et autres.

C’est une des raisons qui font que je me tourne aujourd’hui vers un design d’une app externe en se servant de l’API REST de Simplicité (s’il y en a une disponible évidemment - je préférais un REST API à un SOAP). L’idée est donc de travailler avec la librairie ReactJS ou le framework AngularJS (je dois avouer ma préférence pour ReactJS qui me faciliterait la tâche comparé à une intégration 100%JS et galèrerais sur la configuration de mes routes) et d’afficher les données en faisant appel à Simplicité via un REST API, avec les classiques GET, POST, PUT et DELETE. Utiliser cette méthode me permettrait donc d’avoir le design que je souhaite en affichant ce que je souhaite. Le problème est que je n’ai pas trouvé de doc expliquant clairement l’API de Simplicité (ou je n’ai pas correctement orienté ma recherche, le cas échant, j’en suis désolé) :

  • Oauth2 authentification + token et le garder pour la cession pendant la navigation (je travaille souvent avec le X-CSRToken)
  • le ReadMe classique pour les méthodes d’appel ainsi que les routes et le JSON (ou XML) de réponse comme on peut en trouver sur Github ou l’on peut voir : To get the list of all your propeties :
    GET : api/mydomain/properties/
    And the API endpoint for details :
    All methods : api/mydomain/properties/{id}/
  • Est-ce qu’il y a un moyen de modifier les réponses du Back pour n’afficher que quelques champs dans la réponse à la requête plutôt que les 150 champs de l’objet. Cela permettrait d’augmenter la sécurité car la réponse complète à la requête ne serait pas récupérable.

Je ne sais pas si j’ai étais clair dans ma demande, En attendant votre réponse, Bonne soirée à vous, Thomas

Il y a plusieurs manière de faire des pages spécifiques avec Simplicité:

Ensuite en termes d’APIs il y a plusieurs niveaux sur lesquels vous pouvez taper dans vos pages spécifiques:

  1. L’API de haut niveau UI (cf. https://www.simplicite.io/resources/documentation/04-ui/responsive.md)
  2. L’API de niveau intermédiaire DATA (cf. https://www.simplicite.io/resources/documentation/03-apis/ajax-api.md), NB: les APIs niveau UI ci-dessus sont une surcouche de celles-ci
  3. L’API de bas niveau JSON/REST (cf. https://www.simplicite.io/resources/documentation/02-integration/rest-services.md), qui se décrit notamment en OpenAPI

Selon le type de UI spécifiques que vous envisagez de développer le choix doit se porter de préférence sur l’une ou l’autre histoire de ne pas “réinventer la poudre”.

  • dans un objet externe en zone authentifiée il faut clairement privilégier l’API 1
  • dans un objet externe en zone publique il faut privilégier l’API 1 ou 2
  • dans une UI frontend externe (ex: une appli mobile native iOS ou Android ou un site web spécifique basé sur tel ou tel framework à la mode) il faut privilégier l’API 3
    etc.

Et, bien entendu, toute l’intelligence métier (règles de gestion, calculs, …) de votre application doit exclusivement être développée du coté serveur (typiquement dans les hooks des objets métier). En effet, si vous mettez la moindre l’intelligence métier dans vos UI spécifique vous ne faites clairement pas les choses au bon endroit (pour d’évidentes raisons de mutualisation, homogénéité, sécurité, fiabilité, auditabilité, etc.): vos composants de présentation spécifique (qui appellent les APIs 1, 2 ou 3 ci-dessus) ne doivent faire que de la présentation.

Par exemple le fait de rendre accessibles et/ou modifiables tels ou tels attributs via les accès API relève de règles métier à implémenter coté serveur (il y a pour ça plusieurs approches : héritage, contraintes, hooks, …)

Bonjour David et merci pour cette réponse.

Je pense que je vais partir sur l’API 3 car je m’oriente plus sur une UI frontend externe. Les designs sur lesquels on travaille sont facilement intégrables en ReactJS.

Evidemment, le front ne sera que de l’affichage, aucune règle de gestion, calculs et autres ne sera fait en front. On devrait être sur du ReadOnly pour une grande majorité des champs.

Je vais donc lire la doc 3 et faire des essais sur Postman. Si jamais je rencontre des difficultés, je reviendrais vers vous !

Bonne journée,

Thomas

Oui tu peux faire des tests sur Postman sinon il y a le testeur d’API intégré à Simplicité sur /api, exemple d’usage sur cette video:

Pour rendre accessible tes objets via API il faut créér un groupe de droits front avec les droits qui vont bien (read-only dans ton cas si je comprends bien), il faut créer un user technique (en statut “web services only”) habilité à ce groupe.

Sur la démo il y a le user website et son groupe DEMO_PUBLIC qui est configuré dans cette logique

Je recommanderais aussi de mettre en “forbidden” (via le hook postLoad) les attributs qui n’ont pas à être exposés publiquement (en checkant si le user est dans le groupe front) et/ou jouer sur l’héritage pour avoir des objets back habilités en back qui héritent d’objet front habilités en front plus restreints en termes de nombre d’attributs etc. Bref il faut bien réfléchir à ce qu’on expose en front*…

Une dernière chose, l’authent via user/password est Ok pour un appel ponctuel mais pour une UI front qui fait de nombreux appels successifs il faut impérativement utiliser les tokens, cf. https://www.simplicite.io/resources/documentation/02-integration/services-auth.md

Bonjour David,

Merci pour toutes ses informations et cette documentation, cela m’a été d’une grande utilité. J’ai pu bien cerner et comprendre le REST API de Simplicité.

Cependant j’ai un problème (et j’ai vu dans un autre topic du forum que je n’étais pas le seul) concernant les tokens.

Démarches :
  • Création form login :
    CODE1
    <h1>Login page</h1>
    <form action="./bankAccount.html">
        <h3>Username</h3>
        <input type="text" name="username" id="username">
        <h3>Password</h3>
        <input type="password" name="password" id="password">
        <br>
        <br>
        <input type="button" value="Log in" onclick=login()>
    </form>

Jusqu’ici rien de bien compliqué.

  • Action on click:
    Dans mon fichier JS lié à cette page, j’ai le code suivant :
    CODE2
function login() {
    //Définition des variables 
    var url = "https://immodevthomas.e3m.simplicite.io/";
    var username = document.getElementById("username").value;
    var password = document.getElementById("password").value;

    var xhr = new XMLHttpRequest();

    //Envoi de la requete
    xhr.open("POST", url + "api/login?_json=true", false);
    //Mise en place header url encoded
    xhr.setRequestHeader("Content-type", "application/x-www-form-urlencoded");
    //On passe les paramètres
    xhr.send("username=" + username + "&password=" + password);

    var response = xhr.responseText;
    var JSONresponse = JSON.parse(response)

    //Récupération des variables importantes
    token = JSONresponse.authtoken;
    sessionID = JSONresponse.sessionid;

    //On crée 2 cookies 
    document.cookie = "JSESSIONID=" + sessionID;
    document.cookie = "Reminder=" + "Bearer " + token;

    //On part sur une autre page
    window.location.href = "loginSucess.html";
}

Je suis donc bien connecté, je créé le cookie JSESSIONID dans lequel je mets mon ID de session. Un autre cookie où je mets mon token d’authentification: je le fais passer par un autre cookie car je change de page (et qu’il n’existe pas de variable d’environnement en JS.

  • Sur le fichier JS de la page loginSucess.html (elle est vide d’un point de vue html mais je fais des test pour savoir ce que me renvoie la console)

CODE3

//Variable globale
var url = "https://immodevthomas.e3m.simplicite.io/api/rest/"

//Récupération informations du cookie
console.log(document.cookie);
var token = document.cookie.split("=")[2];

var xhr = new XMLHttpRequest();

//On GET sur l'objet ImmoBankAccount
xhr.open("GET", url + "ImmoBankAccount", false);
xhr.setRequestHeader("X-Simplicite-Authorization", token);
xhr.send();

var response = xhr.responseText;
console.log(response); 

Et je me retrouve avec la réponse suivante :

GET https://immodevthomas.e3m.simplicite.io/api/rest/ImmoBankAccount 401 ()
{ "status": 401, "error": "Jeton non valide" }

Je me suis donc penché sur le topic du forum : Services authentification// Access Token
Et j’ai donc modifié mon CODE2 :
xhr.open("POST", url + "api/login?_json=true&USE_USERTOKEN=yes&USERTOKENS_DURATION=10", false);

Mais j’obtiens toujours la même erreur…
Pourriez me débloquer sur ce sujet ?
Merci d’avance,
Thomas

Cf. ma réponse à ce topic: Services authentification// Access Token

Quelle est la valeur du paramètre système USE_USERTOKEN sur votre(vos) instance(s) ?

Ok, en fait je n’avais pas complètement compris votre réponse sur l’autre topic.
J’ai ensuite passé les paramètres en YES, mais j’avais oublié de faire un petit clear cache…
Tout fonctionne !! Merci beaucoup !

Bonjour,
C’est encore moi !
Je n’arrive pas à faire de requête POST ou PUT afin de modifier un élément :

Aucune règle sur IBAN et BIC (excepté que l’on peut pas avoir 2 IBAN identiques mais ce n’est pas le cas sinon, j’ai la réponse me disant IBAN identique).
Je n’arrive pas à comprendre d’où vient l’erreur étant donné que je passe à JSON.


Merci d’avance pour votre réponse,
Thomas

Quelle est la stratégie d’update concurrent sur cet objet ?

Autre question: dans la mesure où vous semblez écrire du javascript pour page web pourquoi n’utilisez vous pas notre librairie Ajax (cf. https://www.simplicite.io/resources/documentation/03-apis/ajax-api.md), elle vous faciliterait grandement la vie…

En principe, je suis en Optimistic Concurrency, j’ai forcément les droits dessus parce que c’est le profil designer (enfin si c’est bien de cela que l’on parle et si j’ai bien compris Optimistic et Pessimistic).
Concernant Ajax… C’est vrai que je n’y ai pas pensé ! Pour l’instant, je testais un peu en total front externe et tester des appel à l’API Simplicité. Je n’ai réfléchi à ça avant…

Dans Simplicité l’upgrade optimiste/pessimiste est lié au fait que l’objet est time-stamped ou non.

Pour le reste pour du web je recommande vraiment d’utiliser notre lib Ajax car elle gère sessions et tokens de manière transparente et offre un niveau d’abstraction qui la rend simple d’usage en tout cas plus que les services REST de bas niveau. Dans la démo il y a un exemple assez complet de son usage avec l’objet externe DemoWebsite.

À noter que cette lib est celle qui est utilisée (wrappée dans une lib de plus haut niveau) par la UI générique.

En complément à nos échanges, voici un exemple React extrêmement simple qui illustre comment se servir de la lib Ajax dans ce contexte: GitHub - simplicitesoftware/react-demo: Basic React(R) using node.js & browser API

A votre disposition pour en discuter et/ou enrichir cet exemple (on a pas vraiment de compétences React, ce module c’est juste un simple proof of concept).

A l’execution ça donne ça:

NB: la lib chargée dynamiquement <url>/scripts/ajax/bundle.js n’est que la concaténation des libs déjà disponibles dans <url>/scripts/ajax, on a intégré la fabrication de ce bundle à la branche master de Simplicité (l’idée est de se simplifier la vie en ne chargeant qu’un .js au lieu de plusieurs), en fonction de la branche sur laquelle est calée votre instance ce sera donc disponible ce soir ou à la prochaine release

Je vous laisse aussi jeter un coup d’oeil à ce repository GitHub https://github.com/simplicitesoftware/web-demo qui montre comment se servir de la lib Node+Browser (https://github.com/simplicitesoftware/nodejs-api) dans un contexte de frontend web simple.

L’exemple React du post précédent a aussi été mis à jour pour ce servir de cette lib (l’exemple qui charge dynamiquement la lib Ajax de l’instance y reste disponible pour mémoire).

Et on a aussi ajouté un exemple basique ReactNative (https://github.com/simplicitesoftware/react-native-demo) basé sur cette même lib.

Avec ces 3 exemples vous avez normalement les billes pour vous servir de la lib Node+Browser dans différents contextes de frontends custom.

NB: cette lib Node+Browser n’est pas la même chose que la lib standard Ajax disponible sur l’instance, fondamentalement elles font la même chose mais pas exactement de la même manière (la lib Node+Browser utilise une logique de Promises là où la lib Ajax reste en appel avec callback) et, surtout, elles ne s’intègrent pas de la même manière à vos projets.