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.
| Membre | Type | Description |
|---|---|---|
| IPAndPort | Chaine | Interface et port d’écoute (ex : 77.15.224.31:9000). Pour écouter toutes les interfaces d’une machine, indiquer l’adresse IP “0.0.0.0”. 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). Pour utiliser un certificat SSL existant, voir la méthode SetHTTPSCertificate. Pour demander la génération d’un certificat Let’s Encrypt, voir la méthode SetLetsEncryptParameters. |
| Logger | Booléen | Active la journalisation LightREST (très verbeuse, à n’activer qu’en cas de debug du composant) |
| Callback | Procédure | Procé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) |
| Monitoring | Booléen | Activation 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 |
| Constante | Description |
|---|---|
| MethodGET | Méthode REST “GET” |
| MethodPOST | Méthode REST “POST” |
| MethodPUT | Méthode REST “PUT” |
| MethodDELETE | Méthode REST “DELETE” |
| MethodHEAD | Méthode REST “HEAD” |
| MethodPATCH | Méthode REST “PATCH” |
| MethodOPTIONS | Méthode REST “OPTIONS” |
| Méthode | Utilisation |
|---|---|
| AddRoute | Création d’une route REST (association d’une URL+Méthode REST et d’une procédure WinDev) |
| Kill | Stoppe le serveur LightREST |
| SetAuthenticationCheckFunction | Définit la fonction de contrôle de l’authentification du client |
| SetGlobalHeaders | Définit les entêtes (HEADERS) qui seront automatiquement ajoutée à chaque réponse REST |
| SetGlobalOptionsHeaders | Définit les entêtes (HEADERS) qui seront automatiquement ajoutée à chaque réponse REST sur le verbe OPTIONS (CORS) |
| SetHTTPSCertificate | Définit les paramètres HTTPS/SSL : Certificat et Clé Privée |
| SetLetsEncryptParameters | Définit les paramètres de génération et de renouvellement automatiques du certificat SSL Let’s Encrypt |
| Start | Démarre le serveur LightREST |
Méthode AddRoute(Route <type : chaine>, Méthode <type : constante Method*>, Procédure <type : procédure>)
Création d’une nouvelle Route associant un couple Route+Méthode à une procédure WinDev® (ou procédure REST)
| Paramètre | Type | Description |
|---|---|---|
| Route | Chaine | La 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éthode | Chaine | Peut contenir soit une des constantes de type lrServer::Method soit une valeur litérale. |
| Procédure | Procédure | Nom 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ètre | Type | Description |
|---|---|---|
| Procédure | Chaine | Nom 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
FINMé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ètre | Type | Description |
|---|---|---|
| Entêtes | Tableau associatif de Chaînes | Pour 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ètre | Type | Description |
|---|---|---|
| Entêtes | Tableau associatif de Chaînes | Pour 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 existants.
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ètre | Type | Description |
|---|---|---|
| Certificat | Chaîne | Contenu du Certificat SSL |
| Clé Privée | Chaîne | Contenu 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 SetLetsEncryptParameters(Domaine(s), Email, Chemin de stockage du certificat, délai de renouvellement)
Définition des paramètres pour génération d’un certificat Let’s Encrypt.
A utiliser en mode https://
| Paramètre | Type | Description |
|---|---|---|
| Domaine(s) | Chaîne ou Tableau de Chaines | Domaine(s) sur lesquels le certificat doit être généré |
| Chaîne | Email de contact | |
| Chemin certificat | Chaine | Facultatif : Chemin de stockage du certificat Let’sEncrypt (par défaut dans le répertoire de l’exécutable) |
| Délai de renouvellement | Entier | Facultatif : Délai exprimé en jours. Dès que la date d’expiration du certificat moins ce délai sera atteint, LightREST renouvellera automatiquement le certificat SSL auprès de Let’s Encrypt |
Retour : Aucun
Exemple :
Démarrage d’un serveur LightREST en mode HTTPS avec génération automatique d’un certificat SSL Let’s Encrypt, stocké dans le répertoire de l’exécutable, et qui sera renouvelé par LightREST 120 jours avant expiration.
oServer est lrServer
bStartOK est booléen
cErrMess est chaîne
oServer:IpAndPort = "https://0.0.0.0:443"
oServer:SetLetsEncryptParameters("restapi@domaine.com", "contact@codeline.fr", *, 120)
(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 :
| Membre | Type | Description |
|---|---|---|
| IPAndPort | Chaîne | Adresse 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). |
| Callback | Procédure | Procédure WinDev qui sera appelée en cas d’erreur ou d’arrêt du serveur |
| Logger | Booléen | A 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
FINExemple 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
FINMé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:Terminate()
//Le serveur est arrêté proprement, sans interrompre les requêtes en cours de traitement