DO NOT EDIT THE CONTENT OF THIS PAGE DIRECTLY (EXCEPT INSIDE THE DIV BELOW WITH ID=DESCRIPTION), UNLESS YOU KNOW WHAT YOU'RE DOING. |
The RESTful Web Service plugin allows exposing business logic as a RESTful Web Service. About RESTful Web ServicesRESTful Web Services utilize the features of the HTTP Protocol to provide the API of the Web Service. For example, it uses the HTTP Request Types to indicate the type of operation:
Using these 4 HTTP Request Types a RESTful API mimics the CRUD operations (Create, Read, Update & Delete) common in transactional systems. A defining feature of REST is that it is stateless: each call the to a RESTful Web Service is completely stand-alone: it has no knowledge of previous requests. Implementing a RESTful Web Service in ServoyA RESTful Web Service endpoint can be created by creating a Form in a solution and implement one or more of the following methods to the Form:
The RESTful Web Service endpoint is then available through the URL If the method for one of the HTTP Request Types is not implemented, that operation is not available on the endpoint and when attempted to be called a METHOD_NOT_ALLOWED (HTTP 405) error will be thrown. The RESTful Web Service plugin does not have any client side functions or properties: all its magic happens by implementing the methods with the predefined ws_* names on a form. StatelessRESTful Web Services are to be stateless. The RESTful Web Service plugin internally uses a pool of Headless Clients to handle multiple concurrent requests to the REStful Web Service API. 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, no state should be preserved in the headless client at the end of the call to the API. Therefor, make sure any state is cleared at the end of logic. This means at least the following:
Implement ws_read():Object to allow data retrievalBy performing an HTTP GET on the url {serverUrl}/servoy-service/rest_ws/{solutionName}/{formName}, the A byte array can be returned by returning a dataprovider of type MEDIA or a file read from disk.
Implement ws_create(content):Object to allow adding dataBy performing an HTTP POST on the url {serverUrl}/servoy-service/rest_ws/{solutionName}/{formName}, the The
Implement ws_delete():Boolean to allow data removalBy performing an HTTP DELETE on the url {serverUrl}/servoy-service/rest_ws/{solutionName}/{formName}, the Implement ws_update(content):Boolean to allow updating existing dataBy performing an HTTP PUT on the url {serverUrl}/servoy-service/rest_ws/{solutionName}/{formName}, the Implement ws_authenticate(user, password):Object to allow authentificationIf present, it will be called before performing any rest operation (ws_read, ws_create, ws_delete, ws_update). Implement ws_response_headers():Object to allow setting response headersThe method can return either a string or an array of strings of type "headerKey=headerValue". These will be set in the response header. Request parametersAdditional parameters can be specified in the URL of the HTTP Requests. There are two variations and how they are forwarded to the Additional URL path elements
The additional URL path elements {someValue} and {anotherValue} will be passed into the Query parameters If the URL contains Query parameters, these will be passed into the Example
A HTTP Get Request on url {serverUrl}/servoy-service/rest_ws/myRestAPISolution/APIv1/foo/bar?name=John&age=30&pet=Cat&pet=Dog would result in invoking the The ws_read function will be invoked with three parameters: 'foo', 'bar', {name: ['John'] , age: [30] , pet: ['Cat', 'Dog'] }
HTTP RequestFor the POST and PUT operation (resp. The supported Content-Types are JSON (application/json), XML (application/xml) and byte array (application/binary). The Content-Type can be explicitly set in the header of the HTTP Request:
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:
When the Content-Type cannot be determined, an UNSUPPORTED_MEDIA_TYPE response will be generated (HTTP 415). The supplied value in the body of the HTTP request will be applied as argument to the invocation of the method. If the body Content-Type is not application/binary, it will be converted to a JavaScript object automatically. 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. HTTP ResponseBy 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:
By default, the response will be encoded with the UTF-8 charset, if the response Content-Type is not application/binary with byte array as response. 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:
If the response is specified to be of type byte array, the body of the response will contain the actual stream of bytes. Example This is an example of how to get a byte array response using the http plugin provided by Servoy.
Returning custom status codesWhile some of the HTTP Response status codes are hardcoded in the RESTful Webservices plugin (see this documentation), it is possible to control the HTTP Status codes from within the For example, when a ws_update call comes in for a non-existing resource, the HTTP Status Code to return would be a "Not Found" status code, which is a 404. Returning the 404/Not Found HTTP Status code from within a
For convenience purposes, all available HTTP Status Codes are also listed under the HTTP Plugin shipped with Servoy, so instead of throwing the number 404 in the previous example, a more readable way would be to throw plugins.http.HTTP_STATUS.SC_NOT_FOUND See List_of_HTTP_status_codes on Wikipedia for additional information on all status codes It is also possible to append a detailed description for the returned status code
Authentication/AuthorizationThe RESTful Web service plugin can be configured to check authentication/authorization. When access is denied, an UNAUTHORIZED response is generated (HTTP 401). JSONP supportThe 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:
Pool of ClientsTo 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:
SamplesA 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. More information on RESTful Web ServicesSee the following links for more information on RESTful Web Services:
API Docs |
|
|