Principle
The principle of RESTful architecture is to exhibit/ manipulate information via resources identified by a URI (Uniform Resource Identifier) and actions, actions limited in number, carried by HTTP methods (GET, POST, PUT, DELETE, etc.).
Create a RESTful Web service with Adelia Studio involves writing a Visual Adelia Batch program without status in which each public procedure defines a resource addressable via a URI (@Path) and en action (@GET, @POST, etc.).
The medium for the information exchanged between client (consumer) and service (producer) can be based on all the possibilities offered by the HTTP protocol (header, cookie, form, URL segment, URL parameter, body/content).
The definition of information and exchange media is specified in the declaration of parameters (PARAM) of the public procedure and possibly in the URI associated with the resource (for path or query type settings).
Content information (body of the query or response) exchanged via a resource between the client and the service may be in different formats (XML/JSON/etc.).
The definition of the resource must therefore fix the supported formats for incoming information (query; @Consumes) on the one hand and the supported formats for outgoing information (response; @Produces) on the other.
Finally, to be considered a "root resource", i.e. a RESTful service, the program must also be associated with a URI (@Path).
All the defining elements of a resource are fixed using the order WS_CONFIGURE.
All the defining elements of a piece of information (type, medium) are fixed using the order PARAM.
Scope
A RESTful service has a default scope of the "request" type.
The other valid scope, the "application" scope may be preferred to this, not to provide an execution context because the RESTful paradigm is based on a stateless architecture, but to optimize memory management in the host JVM; the "application" scope makes it possible to have a single instance of the service loaded in the memory.
Example of a Visual Adelia Batch program for the production of a RESTful service:
[INIT_PGM]
ws_configure *SERVICE '@Path' '/cars' /* Setting the root resource
[GET_CAR] /* Public procedure; resource
[DECL]
ws_configure *OPERATION '@Path' '/{numberPlate}' /* Associates a URI with the resource
ws_configure *OPERATION '@GET' *BLANK /* Associates an action with the resource
ws_configure *OPERATION '@Produces' 'application/json' /* Specifies the output content format
/* Declaration of parameter variables
ALPHA(15) numberPlate
REF_CLASS(CAR) iCar
/* Definition of input and output information and exchange media
/* Input : an ALPHA (numberPlate); medium: segment of URL [path]
/* Output: an object (iCar); medium: body/content [content]
PARAM numberPlate,I[path],brand iCar,O[content]
The above program defines a RESTful Web service (root resource identified by the URI/cars).
The service declares, via public GET_CAR procedure, an identified resource addressable by the URI / {numberplate} on the one hand and by the @GETaction on the other.
The format of the output content (response) is JSON.
Security
Access to resources exposed by a REST Web service can be secured.
REST service documentation
REST web service documentation and presentation are handled by the Swagger framework and its counterpart Swagger UI.