LightREST

Composant Serveur API REST pour WinDev®
Léger.
Rapide.
Gratuit.
Sans licence Serveur.

La classe lrServer

La classe lrServer est utile pour déterminer les paramètres d’exécution du serveur LightREST, et pour lancer son exécution.

Dans la version actuelle de LightREST, un et un seul serveur peut être instancié dans un exécutable WinDev® (mais on peut évidemment faire cohabiter plusieurs serveurs écoutant des ports différents). Cette limite sera levée dans une prochaine version.

La classe lrServer implémente les Membres, Constantes et Méthodes décrites ci-dessous.

MembreTypeDescription
IPAndPortChaineInterface et port d’écoute (ex : 0.0.0.0:9000).
Pour écouter toutes les interfaces d’une machine, indiquer 0.0.0.0 comme adresse IP.
Choisir un numéro de port rarement utilisé. Si le port choisi est déjà en écoute par un autre processus, le lancement du serveur LightREST échouera et renverra une erreur.
Si l’adresse IP commence par https://, la connexion sera obligatoirement chiffrée en SSL. Si un certificat est fourni avec la méthode lrServer :SetHTTPSCertificate(), il sera utilisé. Dans le cas contraire, LightREST générera automatiquement un certificat et les communications seront chiffrées. Si ce certificat auto-généré est utilisé, il est possible que les applications clients doivent ignorer une alerte indiquant qu’il s’agit d’un certificat non signé par une autorité (ce qui n’affecte en rien la robustesse des algorithmes de chiffrement SSL).
LoggerBooléénActive la journalisation LightREST (très verbeuse, à n’activer qu’en cas de debug du composant)
CallbackProcédureProcédure appelée automatiquement en cas d’arrêt du serveur (volontaire ou sur une erreur).
La procédure doit recevoir une chaîne en paramètre (qui contiendra l’erreur éventuelle)
MonitoringBooléenActivation du monitoring.
Le monitoring ajoute automatiquement à chaque réponse REST des entêtes contenant les temps d’exécution :
– Global : “Chrono”
– LightREST : “Chrono-LightREST”
– De la procédure REST : “Chrono-Methode”

Valeur par défaut : Faux

ConstanteDescription
MethodGETMéthode REST “GET”
MethodPOSTMéthode REST “POST”
MethodPUTMéthode REST “PUT”
MethodDELETEMéthode REST “DELETE”
MethodHEADMéthode REST “HEAD”
MethodPATCHMéthode REST “PATCH”
MethodOPTIONSMéthode REST “OPTIONS”
MéthodeUtilisation
AddRouteCréation d’une route REST (association d’une URL+Méthode REST et d’une procédure WinDev)
KillStoppe le serveur LightREST
SetAuthenticationCheckFunctionDéfinit la fonction de contrôle de l’authentification du client
SetGlobalHeadersDéfinit les entêtes (HEADERS) qui seront automatiquement ajoutée à chaque réponse REST
SetGlobalOptionsHeadersDéfinit les entêtes (HEADERS) qui seront automatiquement ajoutée à chaque réponse REST sur le verbe OPTIONS (CORS)
SetHTTPSCertificateDéfinit les paramètres HTTPS/SSL : Certificat et Clé Privée
StartDémarre le serveur LightREST

Méthode AddRoute(Route, Méthode, Procédure)

Création d’une nouvelle Route associant un couple Route+Méthode à une procédure WinDev® (ou procédure REST)

ParamètreTypeDescription
RouteChaineLa Route sera ajoutée automatiquement à l’adresse du serveur REST, définie lors de l’appel à la méthode lrServer:Start().
Exemple : pour la route “ma_belle_route”, l’URL d’appel sera : http://serveur.com/ma_belle_route
MéthodeChainePeut contenir soit une des constantes de type lrServer::Method soit une valeur litérale.
ProcédureProcédureNom de la procédure WinDev qui va recevoir la requête REST et renvoyer le résultat au client (NB : le nom de la procédure doit être indiqué sans parenthèses, voir exemple).

Retour : Aucun

La route peut contenir des éléments variables encadrés par des accolades {}. Exemple : /client/{id_soc}/{id_client}
Dans ce cas LightREST identifiera la procédure rattachée à la route, quels que soient les paramètres utilisés. La méthode lrRequest:GetVarValue() permettra de récupérer les valeurs passées dans la route.

Exemple 1 :

Création d’une route /ping avec la méthode GET, qui lancera la procédure REST pg_Ping

oServer est lrServer
oServer:AddRoute("/ping", lrServer::MethodGET, pg_Ping)

Exemple 2:

Création d’une route /client avec la méthode POST, qui lancera la procédure REST pg_ClientAdd pour créer une nouvelle entité

oServer est lrServer
oServer:AddRoute("/client", lrServer::MethodPOST, pg_ClientAdd)

Exemple 3:

Création d’une route /client avec la méthode GET, qui lancera la procédure REST pg_ClientGet pour récupérer de données. Cette route inclut des parties variables dont les valeurs pourront être récupérées par la procédure qui gère la route avec la méthode lrRequest:GetVarValue()

oServer est lrServer

oServer:AddRoute("/client/{id_soc}/{id_client}", lrServer::MethodPOST, pg_ClientGet)

Méthode Kill()

Stoppe l’exécution du serveur LightREST.
Aucune vérification n’est effectuée quand à l’exécution en cours d’une fonction REST. Pour garantir qu’aucune interruption hasardeuse n’est possible, utiliser plutôt la méthode Terminate() qui attendra la fin de toutes les routes en cours d’exécution pour arrêter le serveur REST.

Paramètres : Aucun

Retour : Aucun

Exemple :

oServer est lrServer
oServer:Kill()
//Le serveur est arrêté...

Méthode SetAuthenticationCheckFunction(Procédure)

Définition de la fonction de vérification automatique de l’authentification.

Quand un serveur REST contient beaucoup de points d’entrée, il peut être fastidieux d’implémenter une vérification systématique de l’identité, des droits de l’utilisateur ou de la session en cours.
Lorsque la méthode lrServer::SetAuthenticationCheckFunction() est utilisée, LightREST appelera automatiquement la fonction passée en paramètre à chaque fois qu’un client lancera une requête REST.

ParamètreTypeDescription
ProcédureChaineNom de la procédure WinDev qui gère l’authentification

Retour : Aucun

Exemple :
Le code ci-dessous entraînera un appel systématique à pl_CheckAccess() pour chaque Route du serveur exécutée.

oServer est lrServer

oServer:SetAuthenticationCheckFunction(pg_CheckAccess)
...
...
oServer:Start()
...
...


//Code de la procédure globale
PROCEDURE pg_CheckAccess(pRequest est stRequest) : booleen
bOK est booleen

.... Vérification des droits utilisateurs
.... Blablablabla
.... bOK = (pRequest:GetHeaderValue(pRequest, "check") = "blablabla")

    RENVOYER bOK
FIN

Méthode SetGlobalHeaders(Entêtes)

Définition de entêtes OPTIONS (HEADERS) globales.

Quand un serveur REST contient beaucoup de points d’entrée, il peut être fastidieux de renvoyer systématiquement certaines entêtes HTTP. LightREST renverra automatiquement les headers définis ici, quels que soient la route et le verbe utilisés.

ParamètreTypeDescription
EntêtesTableau associatif de ChaînesPour chaque entête globale (HEADER), contient la valeur à renvoyer au client

Retour : Aucun

Exemple :

Définition des entêtes automatiques. Elle seront incluses systématiquement à chaque réponse envoyée.

oServer est lrServer
taHEAD  est tableau associatif de chaînes

taHEAD["Version-Number"]  = "123.45"
taHEAD["Public-Key"]      = "EB6CCD54"

oServer:SetGlobalHeaders(taHEAD)

Méthode SetGlobalOptionsHeaders(Entêtes)

Définition de entêtes OPTIONS (HEADERS) globales.

Quand un serveur REST contient beaucoup de points d’entrée, il peut être fastidieux de renvoyer systématiquement certaines entêtes HTTP.
C’est par exemple valable lorsqu’on doit utiliser les entêtes de type CORS. Ces entêtes autorisent un serveur à distribuer des données à des utilisateurs externes. Une fois les entêtes OPTIONS globables auront été définies, LightREST répondra donnera automatiquement les entêtes CORS aux systèmes distants qui en feront la demande, quelle que soit la route concernée (sur le verbe OPTIONS).

Pour plus de détails sur CORS, voir ICI et ICI.

NB : il reste évidemment possible de répondre aux requêtes de type OPTIONS en déclarant la route correspondante avec la méthode lrServer::MethodOPTIONS. Cette méthode sera exécutée en remplacement de la route OPTIONS automatique de LightREST.

ParamètreTypeDescription
EntêtesTableau associatif de ChaînesPour chaque entête globale (HEADER), contient la valeur à renvoyer au client

Retour : Aucun

Exemple :

Définition des entêtes automatiques de type CORS pour permettre les requêtes cross-domain. Elle seront renvoyés automatiquement pour chaque requête OPTIONS reçue.

oServer est lrServer
taCORS  est tableau associatif de chaînes

taCORS["Access-Control-Allow-Origin"]  = "*"
taCORS["Access-Control-Allow-Headers"] = "Content-Type"

oServer:SetGlobalOptionsHeaders(taCORS)

Méthode SetHTTPSCertificate(Certificat, Clé privée)

Définition des certificat HTTPS / SSL.

A utiliser en mode https:// si vous disposez d’un certificat. Ceci n’est pas obligatoire. En l’absence de certificat SSL, LightREST générera automatiquement un certificat (non signé).
Si le membre IpAndPort n’est pas préfixé par https:// le certificat SSL ne sera pas utilisé.

ParamètreTypeDescription
CertificatChaîneContenu du Certificat SSL
Clé PrivéeChaîneContenu de la clé privée

Retour : Aucun

Exemple :
Démarrage d’un serveur LightREST en mode SSL avec le certificat fourni.

oServer     est lrServer
bStartOK    est booléen
cErrMess    est chaîne
cCertificat est chaîne = fChargeTexte("./certif_ssl.crt")
cClePrivee  est chaîne = fChargeTexte("./certif_ssl.key")

oServer:IpAndPort = "https://0.0.0.0:9800"
oServer:SetHTTPSCertificate(cCertificat, cClePrivee)

(bStartOK, cErrMess) = oServer:Start()
SI PAS bStartOK ALORS
    Erreur(cErrMess)
    RETOUR
FIN

Méthode Start() : (booleen, chaine)

Démarre un serveur LightREST selon les caractéristiques demandées

Paramètres : Aucun

Retour :

  • Booléen : Succès ou pas du démarrage
  • Chaine : Message d’erreur

Les membres de l’objet lrServer permettent de définir :

MembreTypeDescription
IPAndPortChaîneAdresse IP (interface) d’écoute ainsi que le port TCP/IP.
Pour écouter toutes les interfaces d’une machine, indiquer 0.0.0.0 comme adresse IP.
Choisir un numéro de port rarement utilisé. Si le port choisi est déjà en écoute par un autre processus, le lancement du serveur LightREST échouera.
Si l’adresse IP commence par https://, la connexion sera obligatoirement chiffrée en SSL. Si un certificat est fourni avec la méthode lrServer :SetHTTPSCertificate(), il sera utilisé. Dans le cas contraire, LightREST générera automatiquement un certificat et les communications seront chiffrées. Si ce certificat auto-généré est utilisé, il est possible que les applications clients doivent ignorer une alerte indiquant qu’il s’agit d’un certificat non signé par une autorité (ce qui n’affecte en rien la robustesse des algorithmes de chiffrement SSL).
CallbackProcédureProcédure WinDev qui sera appelée en cas d’erreur ou d’arrêt du serveur
LoggerBooléenA positionner à vrai pour passer LightREST en mode DEBUG (à l’attention de ses développeurs).
Attention cela génère un fichier de journalisation volumineux.

Exemple 1 :
Lancement en mode HTTPS avec fourniture d’un certificat

oServer  est lrServer
bStartOK est booléen
cErrMess est chaîne

oServer:IpAndPort = "https://0.0.0.0:9800"
oServer:SetHTTPSCertificate(
    fChargeTexte("./certif_ssl.crt"),
    fChargeTexte("./certif_ssl.key"))

(bStartOK, cErrMess) = oServer:Start()
SI PAS bStartOK ALORS
    Erreur(cErrMess)
    RETOUR
FIN

Exemple 2 :
Lancement en mode HTTPS avec génération automatique d’un certificat par LightREST

oServer  est lrServer
bStartOK est booléen
cErrMess est chaîne

oServer:IpAndPort = "https://0.0.0.0:9800"

(bStartOK, cErrMess) = oServer:Start()
SI PAS bStartOK ALORS
    Erreur(cErrMess)
    RETOUR
FIN

Exemple 3 :
Lancement en mode HTTP sur une interface spécifique :

oServer  est lrServer
bStartOK est booléen
cErrMess est chaîne

oServer:IpAndPort = "192.168.10.2:9800" // "http://192.168.10.2:9800" est équivalent

(bStartOK, cErrMess) = oServer:Start()
SI PAS bStartOK ALORS
    Erreur(cErrMess)
    RETOUR
FIN

Méthode Terminate()

Stoppe l’exécution du serveur LightREST.
La méthode Terminate() qui attendra la fin de toutes les routes en cours d’exécution pour arrêter le serveur REST.
Pour un arrêt immédiat sans précautions, préférer la méthode Kill()

Paramètres : Aucun

Retour : Aucun

NB : Fonction disponible à partir de LightREST v2.7

Exemple :

oServer est lrServer
oServer:Kill()
//Le serveur est arrêté...