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.
To create a RESTful Web Service, create a form in a solution and add one or more of the following methods to the form:
In case the matching method for the specific HTTP operation (GET, POST, DELETE or PUT) does not exists on the form, an INTERNAL_SERVER_ERROR response (HTTP 500) will be generated.
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:
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. If the content in the body of the HTTP Request is missing, a NO_CONTENT response will be generates (HTTP 204).
The supported Content-Types are JSON (application/json) and XML (application/xml). The Content-Type can be explicitly set in the header of the HTTP Request:
Content-Type: application/json; charset=utf-8
Content-Type: application/xml; charset=utf-8
Note: the charset is optional. If not specified, utf-8 will be assumed.
If no valid Content-Type is set, the plugin will try to establish the type of the content based on the first character of the content:
By default, the response will be encoded with the UTF-8 charset. If the HTTP Request specified a different encoding, that will be used instead. If the encoding of the response needs to be different than the request encoding, this can be specified in the HTTP Request by setting the charset value in the Accept header:
h4.Authentication/Authorisation The RESTful Web service plugin can be configured to check authentication/authorisation. The plugins server property rest_ws_plugin_authorized_groups can be set with a comma separated list of groups defined in the built-in security system of Servoy. When the property is filled with usergroups, HTTP Basic authentication is enabled for all webservice requests. The username/password supplied in the HTTP Request is validated against the users registered in Servoy's built-in security system and additionally against group membership. Access is denied if the user does not exists or the supplied password is incorrect, or the user doesn't belong to one of the specified groups. When access is denied, an UNAUTHORIZED response is generated (HTTP 401). h4.JSONP support The plugin supports so-called JSONP: a variation of JSON that allows cross domain data retrieval. The JSONP variation can be invoked by added a "callback" parameter to the HTTP Request URL:
When invoked with the value "myCallback" for the "callback" parameter, the returned JSON value will be wrapped in a function call to the "myCallback" function:
When there are more concurrent requests than the number of clients in the pool, by default the requests will wait until a client becomes available in the pool. This behavior can be altered by setting the "rest_ws_plugin_client_pool_exhausted_action" property of the plugin. The following values are supported for this property:
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.
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.
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
{column:padding=0px|width=80px}{column}{column}{column}
Server Property Summery
{column:padding=0px|width=100%}{column}
Server Property Details
Only authenticated users in the listed groups (comma-separated) have access, when left empty unauthorised access is allowed
The following values are supported for this property:
block (default): requests will wait untill a client becomes available
fail: the request will fail. The API will generate a SERVICE_UNAVAILABLE response (HTTP 503)
grow: allows the pool to temporarily grow, by starting additional clients. These will be automatically removed when not required anymore.