Child pages
  • RESTful Web Services
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 33 Next »

Unknown macro: {sub-section}

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():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 must return a JavaScript object. The object will be serialized and placed in the body of the HTTP Response. If the return value of the method is null, a NOT_FOUND response (HTTP 404) will be generated
  • 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 generate an OK response (HTTP 200)
    • false: to indicate delete failure. This response will generate a NOT_FOUND response (HTTP 404)
  • 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 generate an OK response (HTTP 200)
    • false: to indicate update failure. This response will generate a NOT_FOUND response (HTTP 404)

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.

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 before the end of the method

HTTP Request

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 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:

  • '
    Unknown macro: {'}
    Body content:
    Unknown macro: {"firstName"}

function ws_update()


{code:title=XML example}<firstName>Jane</firstName>}

If the body content cannot be converted to a JavaScript object based on the Content-Type an INTERNAL_SERVER_ERROR response (HTTP 500) will be generated. If the content in the body of the HTTP Request is missing, a NO_CONTENT response will be generates (HTTP 204).

HTTP Response

By default, the plugin will respond with the same Content Type as was specified in the HTTP Request. This can be overruled by specifying a different response Content-Type in the Accept header of the HTTP Request:

Accept: application/json

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:

Accept: application/json; charset=UTF-16

Pool of Clients

To service the requests to the RESTful Web service API, the plugin creates a pool of (headless) clients. The maximum number of clients allowed can be set using the "rest_ws_plugin_client_pool_size" property of the plugin (default value = 5).

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:

  • 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.

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.

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.

Open source

This plugin is open source. The rest_ws.jar file in the <servoy>/application_server/plugins directory contains the source.


Unknown macro: {table}

{column:width=80px}{column}{column}{column}

Unknown macro: {tr}
Unknown macro: {th}

Server Property Summary

Unknown macro: {tbody}
Unknown macro: {tr}
Unknown macro: {td}
Unknown macro: {tbody}
Unknown macro: {tr}
Unknown macro: {td}


Unknown macro: {table}

{column:width=100%}{column}

Unknown macro: {tr}
Unknown macro: {th}

Server Property Details

Unknown macro: {tbody}
Unknown macro: {tr}
Unknown macro: {td}
rest_ws_plugin_client_pool_exhausted_action
Unknown macro: {tr}
Unknown macro: {td}
Unknown macro: {sub-section}
Unknown macro: {sub-section}

Action when no more clients are availiable (block/fail/grow), default = block

Unknown macro: {builder-show}
Unknown macro: {tr}
Unknown macro: {td}

Parameters

Unknown macro: {sub-section}
Unknown macro: {div}
Unknown macro: {sub-section}
Unknown macro: {builder-show}
Unknown macro: {tr}
Unknown macro: {td}

Returns

Unknown macro: {sub-section}
Unknown macro: {sub-section}
Unknown macro: {builder-show}
Unknown macro: {tr}
Unknown macro: {td}

Also see

Unknown macro: {sub-section}
Unknown macro: {sub-section}
Unknown macro: {builder-show}
Unknown macro: {tr}
Unknown macro: {td}

External links

Unknown macro: {sub-section}
Unknown macro: {sub-section}
Unknown macro: {builder-show}
Unknown macro: {tr}
Unknown macro: {td}

Sample

Unknown macro: {sub-section}
Unknown macro: {sub-section}
Unknown macro: {tr}
Unknown macro: {td}
Unknown macro: {tbody}
Unknown macro: {tr}
Unknown macro: {td}
rest_ws_plugin_client_pool_size
Unknown macro: {tr}
Unknown macro: {td}
Unknown macro: {sub-section}
Unknown macro: {sub-section}

Max number of clients used (this defines the number of concurrent requests and licences used), default = 5

Unknown macro: {builder-show}
Unknown macro: {tr}
Unknown macro: {td}

Parameters

Unknown macro: {sub-section}
Unknown macro: {div}
Unknown macro: {sub-section}
Unknown macro: {builder-show}
Unknown macro: {tr}
Unknown macro: {td}

Returns

Unknown macro: {sub-section}
Unknown macro: {sub-section}
Unknown macro: {builder-show}
Unknown macro: {tr}
Unknown macro: {td}

Also see

Unknown macro: {sub-section}
Unknown macro: {sub-section}
Unknown macro: {builder-show}
Unknown macro: {tr}
Unknown macro: {td}

External links

Unknown macro: {sub-section}
Unknown macro: {sub-section}
Unknown macro: {builder-show}
Unknown macro: {tr}
Unknown macro: {td}

Sample

Unknown macro: {sub-section}
Unknown macro: {sub-section}
Unknown macro: {tr}
Unknown macro: {td}
  • No labels