DOCUMENTATION EN LIGNE
DE WINDEVWEBDEV ET WINDEV MOBILE

Aide / WLangage / Fonctions WLangage / Communication / Webservices
  • Présentation
  • Principe de l'appel à une fonction d'un Webservice REST
  • Création d'un Webservice REST
  • Les différentes étapes
  • Etape 1 : Création d'un projet ou d'une configuration de projet de type Webservice REST
  • Etape 2 : Création d'une description d'un Webservice REST
  • Etape 3 : Création des points d'entrée
  • Etape 3 : Méthode 1 : Création manuelle des points d'entrée
  • Composition de la ressource (ou partie d'URL)
  • Gestion des codes retour dans le code des procédures
  • Etape 3 : Méthode 2 : Création automatique des points d'entrée et des procédures (méthodes) pour un fichier présent dans l'analyse
  • Tester et déboguer un Webservice REST
  • Outil de test de Webservice : WDTestRest
  • Génération du Webservice REST
  • Déployer un Webservice REST
  • Déployer un Webservice
  • Cas particulier : Déploiement et test d'un Webservice sur le poste local
  • Appel par programmation d'une fonction REST
  • Quelques exemples
  • Générer la documentation OpenAPI
WINDEV
WindowsLinuxUniversal Windows 10 AppJavaEtats et RequêtesCode Utilisateur (MCU)
WEBDEV
WindowsLinuxPHPWEBDEV - Code Navigateur
WINDEV Mobile
AndroidWidget AndroidiPhone/iPadWidget IOSApple WatchMac CatalystUniversal Windows 10 App
Autres
Procédures stockées
Présentation
Un Webservice REST est un programme hébergé sur un serveur contenant des fonctions accessibles via des requêtes HTTP. Chaque fonction (également appelée API ou point d'entrée) correspond à un traitement exécuté sur le serveur.
Chaque point d'entrée est caractérisé par :
  • une ressource,
  • une méthode HTTP (verbe GET, POST, PUT, ...).
Un Webservice REST peut contenir des points d'entrée ayant une URL identique et des méthodes HTTP différentes (représentant une action différente à réaliser).
Les méthodes HTTP disponibles sont les suivantes :
  • GET pour récupérer des informations.
  • POST pour créer.
  • PUT pour modifier.
  • DELETE pour supprimer.
  • PATCH pour modifier.
  • HEAD pour récupérer des informations.

Principe de l'appel à une fonction d'un Webservice REST

L'appel à une fonction d'un Webservice REST est réalisé via une ressource (URL).
Cette ressource représente à elle seule la nature des informations manipulées ainsi que leur identification. Les méthodes HTTP (verbes) utilisées dans l'adresse permettent d'indiquer la nature de l'action à réaliser.
Dans la fonction, les codes HTTP (2xx, 3xx, 4xx et 5xx) permettent d'indiquer le compte-rendu de la fonction REST.
Par exemple, l'adresse suivante :
http://serveur/Clients/10/Commandes
représente l'action suivante : "Récupérer la liste des commandes du client N° 10".
Dans cette adresse  :
  • serveur représente l'adresse du serveur hébergeant le Webservice REST.
  • Clients indique des données concernant des clients sont manipulées.
  • 10 représente l'identifiant du client à manipuler.
  • Commandes indique des données concernant des commandes sont manipulées.
Cette requête HTTP est effectuée via la méthode GET ce qui indique que des données doivent être récupérées en retour de l'appel.
Création d'un Webservice REST

Les différentes étapes

Pour créer un Webservice REST :
  1. Créez un projet ou une configuration de projet de type Webservice REST.
  2. Créez une ou plusieurs descriptions de Webservice REST. Une description de Webservice REST permet de regrouper une liste de fonctions pour un même thème.
  3. Dans chaque description, créez les points d'entrée nécessaires. Deux méthodes sont disponibles pour créer les points d'entrée : Rappel : Un point d'entrée est constitué de :
    • une procédure ou d'une méthode WLangage.
    • une méthode HTTP.
    • une ressource (partie d'URL).
    • le format de la requête et le format de la réponse.
  4. Le Webservice peut être généré et déployé.

Etape 1 : Création d'un projet ou d'une configuration de projet de type Webservice REST

Pour créer un projet de type Webservice REST :
  1. Créez un nouveau projet :
    • Affichez si nécessaire la page d'accueil (Ctrl + <).
    • Cliquez sur "Créer un projet".
  2. Dans l'assistant de création de projet :
    • Sélectionnez un projet de type "Webservice SOAP ou REST".
    • Choisissez de générer un Webservice REST.
  3. Terminez l'assistant.
Pour créer une configuration de projet de type Webservice REST :
  1. Sous le volet "Projet", dans le groupe "Configuration de projet", déroulez "Nouvelle configuration" et sélectionnez "Webservice".
  2. Dans l'assistant de création d'une configuration de projet, choisissez de générer un Webservice REST.
  3. Terminez l'assistant.

Etape 2 : Création d'une description d'un Webservice REST

Rappel : Une description d'un Webservice REST permet de regrouper une liste de fonctions pour un même thème.
Pour créer une description d'un Webservice REST.
  1. Dans le volet "Explorateur de projet", sélectionnez "Descriptions de Webservices REST", puis dans le menu contextuel (clic droit), sélectionnez "Nouvelle description d'un Webservice REST".
    Création d'une description de Webservice
  2. Saisissez le nom de la description du Webservice REST, puis validez.
  3. L'assistant de saisie d'un nouveau point d'entrée se lance automatiquement.

Etape 3 : Création des points d'entrée

L'assistant de création des points d'entrée d'un Webservice REST est lancé :
  • lors de la création d'une nouvelle description de Webservices REST.
  • sous le volet "Webservice REST", dans le groupe "Points d'entrée", en cliquant sur "Nouveau".
    Volet

    Remarque : Le volet "Webservice REST" est disponible uniquement lorsqu'une description de Webservice REST est affichée sous l'éditeur.
Si le projet est associé à une analyse, l'assistant de création d'un point d'entrée propose de sélectionner la méthode de création des points d'entrée :

Etape 3 : Méthode 1 : Création manuelle des points d'entrée

Dans la suite de l'assistant :
  1. Spécifiez la procédure globale WLangage associée au point d'entrée. Cette procédure peut être créée ou être sélectionnée parmi les procédures globales existantes.
    Choix de la procédure
  2. Passez à l'étape suivante.
  3. Choisissez la méthode HTTP représentant l'action à réaliser (GET, PUT, ...).
    Choix de la méthode HTTP
  4. Passez à l'étape suivante.
  5. Définissez la ressource (ou partie d'URL) correspondant au point d'entrée. Cette ressource peut comporter des éléments statiques ou des éléments variables (paramètres).
    Ressource du point d'entrée
    Pour plus de détails sur la ressource, consultez le paragraphe Composition de la ressource.
  6. Passez à l'étape suivante.
  7. Définissez le format de la requête et le format de la réponse. Le standard en REST est JSON mais d'autres formats sont disponibles.
    • Le format de la requête indique comment sont formatés les données passées lors de l'appel REST.
      Format de la requête
      Ce format peut être sous la forme :
      • Formulaire HTML,
      • JSON,
      • XML,
      • Texte (type MIME "Text/Plain"),
      • Binaire (pour des images par exemple),
      • Variable (le format est libre et doit être indiqué par programmation par la fonction WebserviceLitTypeMIME).
    • Dans le cas d'une action de type POST, PUT ou PATCH, il est possible de désérialiser automatiquement les données passées en paramètre de la requête dans un paramètre de la procédure associée au point d'entrée :
      Désérialisation
      • Cochez la case "Désérialiser automatiquement le contenu...".
        Attention : si la procédure n'a pas de paramètre défini, la case à cocher "Désérialiser automatiquement le contenu..." n'est pas active.
      • Sélectionnez dans la liste le nom du paramètre cible.
        Attention : Vous devez modifier le code de la procédure pour définir le paramètre et revenir dans l'assistant de création du point d'entrée. Il est très important et obligatoire de typer le paramètre de la procédure. Les types de paramètres autorisés dans la procédure sont : buffer, chaîne Ansi, structure, tableau, objet. Les types simples (entier, date, heure, booléen, ...) ne sont pas autorisés.
        Pour plus de détails, consultez WebServices REST : Désérialisation automatique de la requête.
    • Le format de la réponse indique comment sont formatés les données récupérées en retour d'un appel REST.
      Format de la requête
      Ce format peut être sous la forme :
      • Aucun,
      • JSON,
      • XML,
      • Texte (type MIME "Text/Plain"),
      • Binaire (pour des images par exemple),
      • Variable (le format est libre et doit être indiqué par programmation par la fonction WebserviceEcritTypeMIME).
  8. Passez à l'étape suivante.
  9. Saisir la description du point d'entrée (texte libre).
  10. Validez.
La description des différents points d'entrée est affichée sous l'éditeur.
Format de la requête

Composition de la ressource (ou partie d'URL)

La ressource est composée :
  • d'éléments statiques.
  • d'éléments variables.
  • de paramètres communs (optionnels).
Les éléments statiques représentent les objets manipulés. Par exemple, "/Clients" pour manipuler des clients.
Dans l'assistant de création de la ressource, un élément statique correspond à une "Composante fixe".
Les éléments variables identifient les ressources manipulées (un numéro de client, un numéro de commande, ...). Par exemple "/Clients/{NumCli}" permet d'indiquer le client manipulé via son numéro de client.
  • Dans l'assistant de création de l'URL, un élément variable correspond :
    • soit à une composante variable de type paramètre de procédure. Cette composante est récupérée automatiquement dans les paramètres de la procédure WLangage associée.
    • soit à une composante variable de type programmation, récupéré par programmation par la fonction WebserviceParamètre.
  • Un élément variable est représenté par la syntaxe "{Nom composante variable}".
    Par exemple, "/Clients/10" permet de manipuler les clients ayant l'identifiant 10.
  • Il est habituel de passer les éléments variables dans l'URL lors d'un appel à une fonction REST.
  • Chaque composante variable de type programmation, dans la ressource (URL) du point d'entrée correspond à un paramètre passé à la procédure WLangage associée au point d'entrée.
  • Un élément variable est représenté par un nom lors de la définition de l'adresse du point d'entrée dans l'éditeur. Dans le cas d'une composante variable de type programmation, ce nom doit être identique au nom du paramètre dans la procédure WLangage associé au point d'entrée.
    Au moment de l'exécution, la valeur passée dans la ressource (URL) sera récupérée et mise dans la variable. Ce nom est sensible à la casse. Il est donc très important d'utiliser le même nom dans la procédure et dans la ressource (ou inversement) sinon une erreur d'exécution est générée.
Il est possible de combiner plusieurs éléments statiques et plusieurs éléments variables. Par exemple:
  • "/Clients/{idClient}/Factures" pour récupérer les factures d'un client identifié par son idClient.
  • "/Fournisseurs/{idFour}/Produits/{RefProd}" pour récupérer le produit identifié par "RefProd" du fournisseur identifié par "idFour".
La partie Paramètres communs de la description d'un Webservice permet d'avoir:
  • une partie de la ressource identique à tous les points d'entrée. Il n'est donc pas nécessaire de copier cette partie de la ressource systématiquement dans chaque point d'entrée. La modification est réalisée à un seul endroit.
  • une procédure Prologue qui est appelée avant d'exécuter la fonction associée au point d'entrée du Webservice (pour plus de détails, consultez Procédure Prologue). Une procédure de ce type peut permettre par exemple de contrôler un jeton d'authentification (token) lors de l'appel de chaque point d'entrée. La procédure Prologue est une procédure sans paramètres. Cette procédure doit renvoyer :
    • la valeur Vrai pour continuer et exécuter la procédure associée au point d'entrée.
    • la valeur Faux pour arrêter l'appel et ne PAS exécuter la procédure associée au point d'entrée. Dans ce cas, vous devez utiliser la fonction WebServiceEcritCodeHTTP pour indiquer le code erreur de retour (erreur de type 4XX ou 5XX).
Astuce : Il est possible d'utiliser la définition des paramètres communs pour gérer différentes versions du Webservice REST. Par exemple, un paramètre commun nommé "V1" peut être utilisé. Lors de la création d'une évolution ou d'une version 2 du Webservice, il suffit de changer "V1" en "V2" et ainsi tous les points d'entrée ont leur ressource (URL) modifiée.
Pour modifier les paramètres communs, sous le volet "Webservice REST", dans le groupe "Options", cliquez sur "Description".

Gestion des codes retour dans le code des procédures

Le code des procédures WLangage utilisées pour les Webservices REST doivent gérer des comptes-rendus indiquant si la fonction s'est exécutée correctement ou non.
Par convention, dans un Webservice REST, les comptes-rendus d'exécution sont retournés en utilisant les codes retour HTTP. Les codes retour HTTP sont classés par famille :
  • Les codes 2xx correspondent à une action réalisée avec succès.
  • Les codes 3xx correspondent à des erreurs de redirection.
  • Les codes 4xx correspondent à des erreurs du client (méthode HTTP incorrecte, format de donnée envoyé incorrect,...).
  • Les codes 5xx correspondent à des erreurs du serveur (erreur interne à la procédure WLangage, ...)
Le code de retour est renvoyé à l'aide de la fonction WebserviceEcritCodeHTTP.
Exemples de codes retour utilisés :
  • Demande de création d'un client via la méthode HTTP POST. Cette demande a réussi : il faut renvoyer le code 201.
  • Demande de suppression d'un client via la méthode DELETE. Cette demande a échoué à cause d'une erreur d'intégrité retournée par la base de données : il faut renvoyer le code 500 avec un message complémentaire d'explication.
  • Demande de recherche d'un produit en passant en paramètre une référence via la méthode GET. Cette demande a réussi : il faut renvoyer le code 200.
  • Demande de recherche d'un produit en passant en paramètre une référence via la méthode GET. Cette demande a échoué car la référence est inexistante : il faut renvoyer le code 404.

Etape 3 : Méthode 2 : Création automatique des points d'entrée et des procédures (méthodes) pour un fichier présent dans l'analyse

Dans la suite de l'assistant de création d'un point d'entrée :
  1. Sélectionnez le fichier de l'analyse sur lequel vous souhaitez décrire les points d'entrée.
  2. Passez à l'étape suivante.
  3. Sélectionnez les rubriques que vous souhaitez exposer dans le Webservice.
    Ces rubriques seront accessibles en lecture et/ou écriture au travers des points d'entrée du Webservice REST.
  4. Passez à l'étape suivante.
  5. Sélectionnez la clé qui permettra d'accéder à un enregistrement du fichier de données pour le lire, le modifier ou le supprimer.
  6. Passez à l'étape suivante.
  7. Sélectionnez le format utilisé pour l'échange des données lors de l'appel des points d'entrée du Webservice REST. 3 formats sont disponibles :
    • JSON (UTF-8) : Les données envoyées ou retournées sont au format JSON.
    • JSON (UTF-8) (utilisation de la fonction HEnregistrementVersJSON) : Les données sont formatées dans un objet intermédiaire créé à l'aide de la fonction HEnregistrementVersJSON.
    • XML : Les données envoyées ou retournées sont au format XML.
  8. Passez à l'étape suivante.
  9. Sélectionnez la liste des points d'entrée qui seront générés lors de la création du Webservice REST.
    Par défaut, tous les types de points d'entrée sont générés :
    • Création : Ajout d'un enregistrement dans le fichier de données.
    • Lecture : Recherche et lecture d'un enregistrement du fichier de données.
    • Modification : Mise à jour d'un enregistrement du fichier de données.
    • Suppression : Suppression d'un enregistrement du fichier de données.
    • Lecture de tous les enregistrements : Lecture de tous les enregistrements du fichier de données.
  10. Passez à l'étape suivante.
  11. C'est terminé. L'assistant génère le code source en objet (POO) et le Webservice REST avec tous les points d'entrée. La classe créée contient :
    • la déclaration des membres représentant les rubriques de l'enregistrement qui est manipulé (utilisation du MAPPING).
    • la déclaration des différentes méthodes représentant les différents points d'entrée du Webservice REST. Une méthode pour chaque point d'entrée du Webservice REST.
    • une méthode sCréation pour le point d'entrée de type Création.
    • une méthode sLecture pour le point d'entrée de type Lecture.
    • une méthode sModification pour le point d'entrée de type Modification.
    • une méthode Suppression pour le point d'entrée de type Suppression.
    • une méthode sLectureTous pour le point d'entrée de type Lecture de tous les enregistrements.
Tester et déboguer un Webservice REST
WINDEV et WEBDEV permettent de tester votre Webservice REST sous le débogueur. Dans ce cas, il suffit de mettre des points d'arrêt dans le code des procédures du Webservice et de lancer son test (GO).
Pour tester et déboguer un Webservice REST :
  1. Lancez au préalable WDADMIN. WDADMIN est le serveur d'application fourni avec WEBDEV. Ce serveur d'application permet de tester en local les sites WEBDEV et Webservices développés à l'aide de WEBDEV ou WINDEV.
  2. Affichez si nécessaire la description du Webservice REST sous l'éditeur.
  3. Déroulez présent parmi les boutons d'accès rapide et sélectionnez "Déboguer le Webservice".
    Le projet est compilé. La fenêtre suivante s'affiche.
  4. Sélectionnez la méthode de test :
    • Tester le Webservice à l'aide de l'outil de test de l'éditeur : Un outil est fourni en standard avec WINDEV et WEBDEV pour tester individuellement chaque point d'entrée du Webservice (voir ci-dessous).
    • Tester le Webservice avec un programme externe : Choisissez cette option si vous avez écrit un programme spécifique pour appeler le Webservice. A la fin de l'exécution de l'exécutable, le mode test est arrêté.
    • Tester le Webservice manuellement : L'éditeur de WINDEV ou WEBDEV se met en attente d'un appel externe. Par exemple, il est possible d'ouvrir un navigateur et de saisir l'URL de la requête correspondant à un des points d'entrée du Webservice à tester. La requête va être traitée et une réponse sera retournée dans le navigateur.
  5. Cliquez sur le bouton "Lancer le test".

Outil de test de Webservice : WDTestRest

L'outil WDTestRest est fourni en standard avec WINDEV et WEBDEV. Cet outil recense tous les points d'entrée du Webservice à tester.
Le volet de gauche représente :
  • la liste de tous les points d'entrée du Webservice,
  • l'historique de tous les tests effectués.
La partie de droite affiche la liste de tous les points d'entrée testés sous forme de volets.
Pour tester un point d'entrée :
  1. Double-cliquez sur un point d'entrée dans le volet à gauche. Un volet s'ouvre à droite.
  2. Complétez l'URL. Par exemple, remplacez les paramètres attendus entre {...} par une vraie valeur.
  3. Sélectionnez le type d'authentification dans la liste.
  4. Saisissez les paramètres de l'entête si nécessaire.
  5. Cliquez sur le bouton "Envoyer" pour exécuter le test. Le résultat s'affiche.
    • Le volet "Réponse" contient le résultat renvoyé par l'URL.
    • La valeur "Statut" correspond au code de retour HTTP retourné par l'URL.
Le lien "Générer le code WL" permet de générer et de récupérer le code WLangage équivalent au test effectué pour l'inclure dans votre projet.
Pour plus de détails, consultez WDTestRest : Testez vos Webservices REST.
Génération du Webservice REST
Pour générer un Webservice REST:
  1. Générez le Webservice :
    • si la configuration en cours est celle du Webservice :
      • sous le volet "Projet", dans le groupe "Génération", cliquez sur "Générer".
      • cliquez sur l'icône de génération parmi les boutons d'accès rapide.
    • si la configuration en cours n'est pas celle du Webservice : sélectionnez la génération voulue parmi les boutons d'accès rapide.
  2. L'assistant de génération de Webservice se lance.
  3. Indiquez le nom du Webservice. Par défaut, le nom du Webservice correspond au nom du projet en cours.
  4. Validez.
  5. L'assistant de déploiement est automatiquement lancé à la suite.
Déployer un Webservice REST

Déployer un Webservice

Pour être utilisable, un Webservice doit être déployé sur un Serveur d'Application WEBDEV.
Il existe plusieurs méthodes de déploiement :
  • Déploiement du Webservice dans le CLOUD pour les applications PC SOFT.
  • Déploiement du Webservice sur un serveur d'application WEBDEV distant.
  • Création d'un package de déploiement distant.
  • Création d'une installation par média physique.
  • Création d'une image Docker du Webservice.
  • Déploiement du Webservice via le service d'hébergement de test PC SOFT.
  • Déploiement du Webservice sur le poste local.
Les options de déploiement d'un Webservice sont identiques à celles de déploiement d'un site WEBDEV. Pour plus de détails, consultez Déploiement d'un site.

Cas particulier : Déploiement et test d'un Webservice sur le poste local

Il est possible de tester le Webservice créé directement sur le poste du développeur. Pour cela, il suffit de choisir l'option "Déployer le Webservice sur le poste local". Ce type d'installation est disponible uniquement si WEBDEV est disponible sur le poste de développement. Dans ce cas, le serveur d'application utilisé est celui de WEBDEV.
A la fin de l'installation, un écran s'affiche avec un lien permettant d'afficher la description du Webservice.
Le Webservice est prêt à être utilisé.
Appel par programmation d'une fonction REST
La fonction RESTEnvoie permet d'appeler une fonction d'un Webservice REST. Pour cela, vous devez:
  • Utiliser une variable de type httpRequête pour décrire la fonction REST à appeler :
    • La propriété URL décrit l'adresse (URL) de la fonction du Webservice REST.
    • La propriété Méthode décrit la méthode HTTP (GET, PUT, ...).
    • La propriété ContentType décrit le type de la donnée à envoyer en paramètre à la fonction du Webservice REST.
    • La propriété Contenu contient les données à envoyer en paramètre à la fonction du Webservice REST.
    • les éventuels paramètres à passer.
  • Utiliser une variable de type restRéponse pour récupérer le résultat de la fonction REST :
    • La propriété CodeEtat contient le code erreur de retour.
    • La propriété Contenu contient les données de la réponse.

Quelques exemples

  • L'exemple de code ci-dessous montre comment récupérer les informations d'un client par son numéro. Si le client n'existe pas, un code 200 est retourné.
    nNumClient est un entier
     
    nNumClient = 2
     
    h est un httpRequête
    h.Méthode=httpGet
    h.URL = "http://localhost/V1/Clients/" + nNumClient
     
    r est un restRéponse = RESTEnvoie(h)
    SI r.CodeEtat = 200 ALORS
    Info(r.Contenu)
    SINON
    Info("Client inexistant", r.Contenu)
    FIN
  • L'exemple de code ci-dessous montre comment supprimer un client par son numéro. Si le client n'existe pas, un code 404 est retourné.
    nNumClient est un entier
     
    nNumClient = 267
     
    h est un httpRequête
    h.Méthode = httpDelete
    h.URL = "http://localhost/V1/Clients/" + nNumClient
     
    r est un restRéponse = RESTEnvoie(h)
     
    SI r.CodeEtat = 404 ALORS
    Info("Client NON trouvé.")
     
    SINON
    Info("Le client a été supprimé avec succès")
    FIN
  • L'exemple de code ci-dessous montre comment ajouter un client. Si l'ajout du client a réussi, un code 201 est retourné.
    NouveauCli est un Buffer
    vCli est un Variant
     
    vCli.nomClient = "DUPONT"
    vCli.societe = "Société DUP"
    vCli.ville = "MONTPELLIER"
     
    NouveauCli = VariantVersJSON(vCli)
     
    h est un httpRequête
    h.Méthode = httpPost
    h.URL = "http://localhost/V1/Clients"
    h.ContentType = "application/json"
    h.Contenu = NouveauCli
     
    r est un restRéponse = RESTEnvoie(h)
    SI r.CodeEtat = 201 ALORS
    Info(r.Contenu)
    SINON
    Info("Erreur de création de client", r.Contenu)
    FIN
Générer la documentation OpenAPI
Il est possible de générer la documentation OpenAPI du Webservice REST : sous le volet "Webservice REST", dans le groupe "Oprtions", cliquez sur "Documentation OpenAPI..." et sélectionnez l'emplacement où le fichier YAML correspondant doit être généé.
Version minimum requise
  • Version 22
Documentation également disponible pour…
Commentaires
Cliquez sur [Ajouter] pour publier un commentaire

Dernière modification : 26/04/2023

Signaler une erreur ou faire une suggestion | Aide en ligne locale