View Source

{hidden}
DO NOT EDIT THE CONTENT OF THIS PAGE DIRECTLY, UNLESS YOU KNOW WHAT YOU'RE DOING.
		THE STRUCTURE OF THE CONTENT IS VITAL IN BEING ABLE TO EXTRACT CHANGES FROM THE PAGE AND MERGE THEM BACK INTO SERVOY SOURCE{hidden}
{sub-section:description|text=}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:
- ws_read() 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().
- ws_create() 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 can be supplied in the body of the HTTP request.
- ws_delete() 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 invokation of ws_delete().
- ws_update() 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 can be supplied in the body of the HTTP request.

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 HTTP 503 response.

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]

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.

{note:title=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.{note}{sub-section}\\{table:class=servoy sSummery}{colgroup}{column:width=80px}{column}{column}{column}{colgroup}{tr:style=height: 30px;}{th:colspan=2}Server Property Summary{th}{tr}{tbody}{tr}{td}{td}{td}[#rest_ws_plugin_client_pool_exhausted_action]
{td}{tr}{tbody}{tbody}{tr}{td}{td}{td}[#rest_ws_plugin_client_pool_size]
{td}{tr}{tbody}{table}\\{table:class=servoy sDetail}{colgroup}{column:width=100%}{column}{colgroup}{tr:style=height: 30px;}{th:colspan=1}Server Property Details{th}{tr}{tbody:id=420C89DC-38E1-4B81-8126-9F53F84B74E5}{tr:id=name}{td}h6.rest_ws_plugin_client_pool_exhausted_action{td}{tr}{tr:id=des}{td}{sub-section:420C89DC-38E1-4B81-8126-9F53F84B74E5_des|text=|trigger=button}{sub-section}{sub-section:420C89DC-38E1-4B81-8126-9F53F84B74E5_des|trigger=none|class=sIndent}Action when no more clients are availiable (block/fail/grow), default = block{sub-section}{td}{tr}{builder-show:permission=edit}{tr:id=prs}{td}*Parameters*\\{sub-section:420C89DC-38E1-4B81-8126-9F53F84B74E5_prs|text=|trigger=button}{sub-section}{div:class=sIndent}{sub-section:420C89DC-38E1-4B81-8126-9F53F84B74E5_prs|trigger=none}{sub-section}{div}{td}{tr}{builder-show}{builder-show:permission=edit}{tr:id=ret}{td}*Returns*\\{sub-section:420C89DC-38E1-4B81-8126-9F53F84B74E5_ret|text=|trigger=button}{sub-section}{sub-section:420C89DC-38E1-4B81-8126-9F53F84B74E5_ret|trigger=none|class=sIndent}{sub-section}{td}{tr}{builder-show}{builder-show:permission=edit}{tr:id=see}{td}*Also see*\\{sub-section:420C89DC-38E1-4B81-8126-9F53F84B74E5_see|text=|trigger=button}{sub-section}{sub-section:420C89DC-38E1-4B81-8126-9F53F84B74E5_see|class=sIndent|trigger=none}{sub-section}{td}{tr}{builder-show}{builder-show:permission=edit}{tr:id=link}{td}*External links*\\{sub-section:420C89DC-38E1-4B81-8126-9F53F84B74E5_see|text=|trigger=button}{sub-section}{sub-section:420C89DC-38E1-4B81-8126-9F53F84B74E5_link|class=sIndent|trigger=none}{sub-section}{td}{tr}{builder-show}{builder-show:permission=edit}{tr:id=sam}{td}*Sample*\\{sub-section:420C89DC-38E1-4B81-8126-9F53F84B74E5_sam|text=|trigger=button}{sub-section}{sub-section:420C89DC-38E1-4B81-8126-9F53F84B74E5_sam|class=sIndent|trigger=none}{sub-section}{td}{tr}{builder-show}{tr:class=lastDetailRow}{td}{td}{tr}{tbody}{tbody:id=4059D6A1-372F-4C41-BEA9-3870E51A198A}{tr:id=name}{td}h6.rest_ws_plugin_client_pool_size{td}{tr}{tr:id=des}{td}{sub-section:4059D6A1-372F-4C41-BEA9-3870E51A198A_des|text=|trigger=button}{sub-section}{sub-section:4059D6A1-372F-4C41-BEA9-3870E51A198A_des|trigger=none|class=sIndent}Max number of clients used (this defines the number of concurrent requests and licences used), default = 5{sub-section}{td}{tr}{builder-show:permission=edit}{tr:id=prs}{td}*Parameters*\\{sub-section:4059D6A1-372F-4C41-BEA9-3870E51A198A_prs|text=|trigger=button}{sub-section}{div:class=sIndent}{sub-section:4059D6A1-372F-4C41-BEA9-3870E51A198A_prs|trigger=none}{sub-section}{div}{td}{tr}{builder-show}{builder-show:permission=edit}{tr:id=ret}{td}*Returns*\\{sub-section:4059D6A1-372F-4C41-BEA9-3870E51A198A_ret|text=|trigger=button}{sub-section}{sub-section:4059D6A1-372F-4C41-BEA9-3870E51A198A_ret|trigger=none|class=sIndent}{sub-section}{td}{tr}{builder-show}{builder-show:permission=edit}{tr:id=see}{td}*Also see*\\{sub-section:4059D6A1-372F-4C41-BEA9-3870E51A198A_see|text=|trigger=button}{sub-section}{sub-section:4059D6A1-372F-4C41-BEA9-3870E51A198A_see|class=sIndent|trigger=none}{sub-section}{td}{tr}{builder-show}{builder-show:permission=edit}{tr:id=link}{td}*External links*\\{sub-section:4059D6A1-372F-4C41-BEA9-3870E51A198A_see|text=|trigger=button}{sub-section}{sub-section:4059D6A1-372F-4C41-BEA9-3870E51A198A_link|class=sIndent|trigger=none}{sub-section}{td}{tr}{builder-show}{builder-show:permission=edit}{tr:id=sam}{td}*Sample*\\{sub-section:4059D6A1-372F-4C41-BEA9-3870E51A198A_sam|text=|trigger=button}{sub-section}{sub-section:4059D6A1-372F-4C41-BEA9-3870E51A198A_sam|class=sIndent|trigger=none}{sub-section}{td}{tr}{builder-show}{tr:class=lastDetailRow}{td}{td}{tr}{tbody}{table}