Using the RESTful Web Service plugin business logic can be exposed as a RESTful Web Service. The RESTful Web Service plugin does not contain any client side functions or properties, it is a 100% server side operating plugin.
API creation
To create a RESTful Web Service, create a form in a solution and add one or more of the following methods to the form:
- ws_read():Object to retrieve data
By performing an HTTP GET on the url <serverUrl>/servoy-service/rest_ws/solutionName/formName, the ws_read() method will be invoked. Arguments can be specified in the url, like <serverUrl>/servoy-service/rest_ws/solutionName/formName/value1/value2. The arguments will be applied to the invokation of ws_read().
The method can return a JavaScript object. The object will be serialized and placed in the body of the HTTP Response. - ws_create():Object to add data
By performing an HTTP POST on the url <serverUrl>/servoy-service/rest_ws/solutionName/formName, the ws_create() method will be invoked. Data has to be supplied in the body of the HTTP request.
The method can return a JavaScript object. The object will be serialized and placed in the body of the HTTP Response. - ws_delete():Boolean to remove data
By performing an HTTP DELETE on the url <serverUrl>/servoy-service/rest_ws/solutionName/formName, the ws_delete() method will be invoked. Arguments can be specified in the url, like <serverUrl>/servoy-service/rest_ws/solutionName/formName/value1/value2. The arguments will be applied to the invocation of ws_delete().
The method has to return a Boolean value:- true: to indicate successful deletion. This result will map to an HTTP 200 response
- false: to indicate delete failure. This response will map to an HTTP 404 response
- ws_update():Boolean to update data
By performing an HTTP PUT on the url <serverUrl>/servoy-service/rest_ws/solutionName/formName, the ws_delete() method will be invoked. Data has to be supplied in the body of the HTTP request.
The method has to return a Boolean value:- true: to indicate successful update. This result will map to an HTTP 200 response
- false: to indicate update failure. This response will map to an HTTP 404 response
In case the matching method for the specific HTTP operation (GET, POST, DELETE or PUT) does not exists on the form, the API will automatically generate a NOT_FOUND response (HTTP 404).
Content-Types
For the POST and PUT operation (resp. ws_create() and ws_update() methods), data has to be supplied in the body of the HTTP Request. The supported Content-Types are JSON (application/json) and XML (application/xml). The supplied value in the body of the HTTP request will be applied as argument to the invocation of the method. If the content in the body of the HTTP Request is missing, a NO_CONTENT response will be generates (HTTP 204). When no or another content type than JSON or XML is specified, an UNSUPPORTED_MEDIA_TYPE response will be generated (HTTP 415)
Stateless
RESTful Web Services are to be stateless. As subsequent requests to the RESTful Web Service API might be handled by different headless clients in the pool of clients configured for the plugin, do not use any state in between calls to the API. This means at least the following:
- Do not use global or form variables
- Do not use the solution model API
- Do not alter the state of the a form's UI
- Do save or rollback any unsaved changes
For more information on RESTful Web Services, see:
http://en.wikipedia.org/wiki/Representational_State_Transfer
http://www.infoq.com/articles/rest-introduction
http://www.ibm.com/developerworks/webservices/library/ws-restful/
http://home.ccil.org/~cowan/restws.pdf
Samples
A sample solution is included in the Servoy distribution (servoy_sample_rest_ws.servoy), detailing how to retrieve data from the http request and to return a response.
Authentication
the RESTful Web service plugin currently does not support authentication
RESTful Web Services & [Servoy Cluster]
The RESTful Web service plugin uses a pool of headless clients to service the requests. When operated within a Servoy Cluster, note that poolsize is set per Servoy Application Server.
{column:width=80px}{column}{column}{column}
Server Property Summary
{column:width=100%}{column}
Server Property Details
Action when no more clients are availiable (block/fail/grow), default = block
Parameters
Returns
Also see
External links
Sample
Max number of clients used (this defines the number of concurrent requests and licences used), default = 5
Parameters
Returns
Also see
External links
Sample