Principe
Le principe de l'architecture REST est d'exposer/manipuler des informations via des ressources identifiées par une URI (Uniform Resource Identifier) et des actions, actions en nombre limité, portées par les méthodes du protocole HTTP (GET, POST, PUT, DELETE…).
Créer un service Web REST avec Adélia Studio consiste à écrire un programme Visual Adélia Batch sans état dans lequel chaque procédure publique définit une ressource adressable par le biais d'une URI (@Path) et d'une action (@GET, @POST,…).
Le support des informations échangées entre le client (consommateur) et le service (producteur) peut reposer sur toutes les possibilités offertes par le protocole HTTP (header, cookie, formulaire, segment d'URL, paramètre d'URL, corps/contenu).
La définition des informations et des supports d'échange est précisée dans la déclaration des paramètres (PARAM) de la procédure publique et éventuellement dans l'URI associée à la ressource (pour les paramètres de nature path ou query).
L'information de contenu (corps de la requête ou de la réponse) échangée via une ressource entre le client et le service peut revêtir différents formats (XML/JSON/etc.).
La définition de la ressource doit donc fixer les formats supportés pour une information entrante (requête ; @Consumes) d'une part et les formats supportés pour une information sortante (réponse ; @Produces) d'autre part.
Enfin pour être considéré comme une "ressource racine", c'est-à-dire un service REST, le programme doit également être associé à une URI (@Path).
Tous les éléments de définition d'une ressource sont fixés à l'aide de l'ordre SW_CONFIGURER.
Tous les éléments de définition d'une information (type, support) sont fixés à l'aide de l'ordre PARAM.
Portée
Un service REST a une portée par défaut de type "request".
L'autre portée valide, la portée "application", peut lui être préférée, non pas pour conserver un contexte d'exécution car le paradigme REST repose sur une architecture sans conservation d'état (stateless), mais pour optimiser la gestion de la mémoire dans la JVM hôte; la portée "application" permet en effet d'avoir une seule instance du service chargée en mémoire.
Exemple d'un programme Visual Adélia Batch pour la production d'un service REST :
[INIT_PGM]
sw_configurer *SERVICE '@Path' '/cars' /* Définition de la ressource racine
[GET_CAR] /* Procédure publique ; ressource
[DECL]
sw_configurer *OPERATION '@Path' '/{numberPlate}' /* Associe une URI à la ressource
sw_configurer *OPERATION '@GET' *BLANK /* Associe une action à la ressource
sw_configurer *OPERATION '@Produces' 'application/json' /* Définit le format du contenu en sortie
/* Déclaration des variables paramètres
ALPHA(15) numberPlate
REF_CLASSE(CAR) iCar
/* Définition des informations en entrée, en sortie et des supports d'échange
/* En entrée : un ALPHA (numberPlate) ; support : segment d'URL [path]
/* En sortie : un objet (iCar) ; support : corps/contenu [content]
PARAM numberPlate,I[path],marque iCar,O[content]
Le programme ci-dessus définit un service Web REST (ressource racine identifiée par l'URI /cars).
Le service déclare, via la procédure publique GET_CAR, une ressource identifiée et adressable par l'URI /{numberPlate} d'une part et par l'action @GET d'autre part.
Le format du contenu en sortie (réponse) est du JSON.
Sécurité
L'accès aux ressources exposées par un service Web REST peut être sécurisé.
Documentation d'un service REST
La documentation et la présentation d'un service Web REST sont prises en charge par le Framework Swagger et son pendant, Swagger-ui.