API Rest WeeMake

Description

Les APIs WeeMake permettent de récupérer des données depuis WeeMake, et de modifier, créer et supprimer des données dans la base WeeMake.

Fonctionnement

Login

La connexion aux APIs se fait via requête POST et utilise les login/password des utilisateurs WeeMake. La recommandation est d'utiliser un utilisateur dédié aux APIs avec des droits dédiés.

Les autorisations API dépendent des droits de l'utilisateur utilisé, pour les imports il faut que l'utilisateur utilisé pour les APIs soit administrateur.

La méthode login/token retourne un token de connexion à utiliser dans toutes les requêtes suivantes. Sa durée de vie est de 10 minutes environ, il est donc recommandé de demander un nouveau token avant chaque série de requêtes API.

Appel API

Lors d'un appel API, les différents paramètres à renseigner sont les suivants :

• URL : /login/token

• Méthode : POST

• Paramètres :

  • login=<login utilisateur>

  • pass=<mot de passe de l'utilisateur>

• Réponse : un token à utiliser dans toutes les requêtes suivantes

Exemple cURL

$ curl -X POST -F 'login=api' -F 'pass=api' https://client.weemake.biwee.fr/login/token
numero_token

Récupération de données

La récupération de données se fait au format CSV de la même façon que l'export CSV réimportable depuis le front-office. L'URL de cet export se fait en utilisant la même URL que la liste en front-office avant le premier slash (contrôleur) avec "api" après le 2eme slash (méthode) Il est possible de spécifier un identifiant avec le paramètre id (peu importe le nom réel du champ identifiant)

Exemple : Liste des objets de type "exmpl" URL front : https://client.weemake.biwee.fr/object_entity_exmpl/list URL API : GET https://client.weemake.biwee.fr/object_entity_exmpl/api

Appel API

• URL : /<contrôleur>/api

• Méthode : GET

• Paramètres :

  • token=<token récupéré avec l'appel à login/token>

  • id=<id d'objet> (optionnel)

• Réponse : CSV

Format du CSV :

• Encodage : UTF-8

• Séparateur : virgule ,

• Enclosure : Guillemets Doubles "

Exemple cURL

$ curl -X GET https://client.weemake.biwee.fr/object_entity_exmpl/api?token=numero_token            
"object_id","title","attr_a","nombre","updated_at","created_at"
"199","Exemple","CCC","789","2021-04-19 11:55:13","2021-04-19 11:55:13"
"198","Lorem Ipsum","BBB","456","2021-04-19 11:54:58","2021-04-19 11:54:58"
"197","test","AAA","123","2021-04-19 11:54:33","2021-04-19 11:54:33"

Avec filtre par identifiant :

$ curl -X GET "https://client.weemake.biwee.fr/object_entity_exmpl/api?token=numero_token&id=198"
"object_id","title","attr_a","nombre","updated_at","created_at"
"198","Lorem Ipsum","BBB","456","2021-04-19 11:54:58","2021-04-19 11:54:58"

Mise à jour, Création et Suppression de données existantes

La mise à jour, la création et la suppression des données se font avec le même principe que l'import CSV en front-office. L'URL d'appel API est identique a celle de récupération mais en méthode POST. Il est nécessaire de spécifier si l'on souhaite créer/modifier/supprimer avec des paramètres dans la chaine d'appel (query string) Le CSV à importer est à envoyer comme corps de la requête POST.

Exemple : objets de type "exmpl"

URL front : https://client.weemake.biwee.fr/object_entity_exmpl/list

URL API : POST https://client.weemake.biwee.fr/object_entity_exmpl/api

Appel API

• URL : /<contrôleur>/api

• Méthode : POST

• Paramètres :

  • token=<token récupéré avec l'appel à login/token>

  • create=1 (optionnel)

  Si =1 alors les lignes du CSV sans id valorisé seront créées

  • update=1 (optionnel)

  Si =1 alors les lignes avec un id valorisé pour un enregistrement existant seront mis à jour

  • delete=1 (optionnel)

  Si =1 alors les lignes avec un id valorisé et la colonne DELETE valorisée à DELETE seront supprimées

• Corps : CSV à importer

• Réponse : Rapport d'importation avec erreurs éventuelles

Format du CSV :

• Encodage : UTF-8

• Séparateur : virgule ,

• Enclosure : Guillemets Doubles "

Exemple cURL > Nouvel enregistrement

Création du CSV :

$ echo '"object_id","title","attr_a","nombre"' > /tmp/import_api.csv                                                                                        
$ echo '"","Nouvel exemple","DDD","999"' >> /tmp/import_api.csv

Envoi du CSV :

$ cat /tmp/import_api.csv | curl --data-binary @- -X POST "https://client.weemake.biwee.fr/object_entity_exmpl/api?token=numero_token&create=1"
1 ROW(S) READ
0 CREATED
1 UPDATED
0 DELETED

Exemple cURL > Mise à jour d'un enregistrement avec toutes les colonnes

Création du CSV :

$ echo '"object_id","title","attr_a","nombre"' > /tmp/import_api.csv                                                                                        
$ echo '"198","Lorem Ipsum MAJ","MAJ","1"' >> /tmp/import_api.csv

Envoi du CSV :

$ cat /tmp/import_api.csv | curl --data-binary @- -X POST "https://client.weemake.biwee.fr/object_entity_exmpl/api?token=numero_token&update=1"
1 ROW(S) READ
0 CREATED
1 UPDATED
0 DELETED

Exemple cURL > Mise à jour d'un enregistrement avec une seule colonne

Création du CSV :

$ echo '"object_id","nombre"' > /tmp/import_api.csv                                                                                        
$ echo '"197","1"' >> /tmp/import_api.csv
$ echo '"198","2"' >> /tmp/import_api.csv
$ echo '"202","3"' >> /tmp/import_api.csv

On voit que le CSV ne contient que la colonne correspondant à l'attribut à changer, les autres ne seront pas mis à jour.

$ cat /tmp/import_api.csv | curl --data-binary @- -X POST "https://client.weemake.biwee.fr/object_entity_exmpl/api?token=numero_token&update=1"
3 ROW(S) READ
0 CREATED
3 UPDATED
0 DELETED

Exemple cURL > suppression d'un enregistrement

Création du CSV :

$ echo '"object_id","__DELETE__"' > /tmp/import_api.csv                                                                                        
$ echo '"199","__DELETE__" >> /tmp/import_api.csv

Envoi du CSV :

$ cat /tmp/import_api.csv | curl --data-binary @- -X POST "https://client.weemake.biwee.fr/object_entity_exmpl/api?token=numero_token&delete=1"
1 ROW(S) READ
0 CREATED
0 UPDATED
1 DELETED

Exemple cURL > ajout + suppression + mise à jour dans un seul fichier

Création du CSV :

$ echo '"object_id","title","attr_a","nombre","__DELETE__"' > /tmp/import_api.csv
$ echo '"","Nouvel exemple","DDD","999",""' >> /tmp/import_api.csv => AJOUT
$ echo '"202","","","","__DELETE__"' >> /tmp/import_api.csv        => SUPPRESSION
$ echo '"197","Test","ABC","123",""' >> /tmp/import_api.csv        => MODIFICATION 

Envoi du CSV :

$ cat /tmp/import_api.csv | curl --data-binary @- -X POST "https://client.weemake.biwee.fr/object_entity_exmpl/api?token=numero_token&create=1&update=1&delete=1"
3 ROW(S) READ
1 CREATED
1 UPDATED
1 DELETED

Explorer la base WeeMake hors objets

Il est possible de faire les mêmes manipulations sur toutes les listes de WeeMake, que ce soit des objets ou non. Il suffit pour cela de vérifier sur la liste que le bouton exporter soit accessible pour pouvoir faire un GET, et que le bouton importer soit disponible pour pouvoir faire un POST.

Exemple 1 : lister les types d'objets

liste front-office : https://client.weemake.biwee.fr/object_type
URL API : https://weedb.biwee.fr/object_type/api
ligne de commande cURL : $ curl -X GET https://weedb.local/object_type/api?token=numero_token

Exemple 2 : lister les rôles utilisateur

liste front-office : https://client.weemake.biwee.fr/admin_role
URL API : https://client.weemake..biwee.fr/admin_role/api
ligne de commande cURL : $ curl -X GET https://weedb.local/admin_role/api?token=numero_token