DataSnap REST

From RAD Studio
Jump to: navigation, search

Go Up to Developing DataSnap Applications

Representational State Transfer (REST) is the client-server architecture used by the World Wide Web. Conforming to REST constraints is referred to as being RESTful. A RESTful web service is implemented using HTTP (hypertext transfer protocol) and the principles of REST.

Topics

DataSnap REST Overview

The REST protocol assumes that the server is able to serve four types of requests: GET, POST, PUT, and DELETE. These operations represent Retrieve, Update, Insert, and Delete data operations. These operations are assimilated with the server methods through a mapping protocol. REST assumes that each server method can be invoked as one of the operations above through a dispatch mechanism that assumes a mapping between the URI (Uniform Resource Identifier) path, method name, and parameters.

URI Mapping

The server responds to URIs. The general HTTP request has the following format:

http://my.site.com/datasnap/rest/URIClassName/URIMethodName[/inputParameter]*

The content is accepted by POST and PUT requests, assimilated with Update and Put requests. The default protocol maps the URI to various server methods depending on the command type.


Command type Mapping pattern Example

GET

URICclassName.URIMethodName

Utility.Storage

PUT

URIClassName.acceptURIMethodName

Utility.acceptStorage

POST

URIClassName.updateURIMethodName

Utility.updateStorage

DELETE

URIClassName.cancelURIMethodName

Utility.cancelStorage


Depending on the command type, a request such as http://my.site.com/datasnap/rest/utility/storage can be mapped to one of the four methods above, depending on the command type. It is assumed that a method mapped through a GET request returns the object, or a collection of objects based on the input parameters.

For example, a server method called Utility.Storage(Key: String): TJSONValue; matches the GET command:

http://my.site.com/datasnap/rest/utility/storage/test.

A POST request will invoke Utility.UpdateStorage(Key: String; Data: TJSONValue);. The request content is mapped to the input parameter data, the URI postfix is mapped to the key.

A PUT request will invoke Utility.AcceptStorage(Key: String; Data: TJSONValue);. The method is assumed to insert into the storage area the data parameter under the key provided. The request content is mapped to the second input parameter.

Finally, a DELETE request will invoke Utility.CancelStorage(Key: String); that is supposed to remove the object from the storage area with the given key.

The mapping pattern can be overridden. The user can override the mapping for each type based on class name and method name parameters.

Customizing the URL for REST Requests

You can easily customize parts of the URL for a REST request. You can change the standard DataSnap context from datasnap/ to mycontext/, for instance. Also, you can change the REST context from rest/ to myrest/, for instance. To do this:

  1. Switch to the WebModule of your DataSnap REST server application.
  2. Select the TDSHTTPWebDispatcher component.
  3. In the Object Inspector, locate the DSContext property.
  4. Change from datasnap/ to mycontext/ (or whatever you require). Remember to add the closing /.
  5. In the Object Inspector, locate the WebDispatch property and expand it.
  6. Update the PathInfo subproperty from datasnap* to mycontext*.
  7. In the Object Inspector, locate the RESTContext property.
  8. Change from rest/ to myrest/ (or whatever you require). Remember to add the closing /.

UpdateRESTParameters.png

These changes will cause the DataSnap server to process requests that begin with

/mycontext/myrest

instead of

/datasnap/rest

Additionally, some changes are needed so that clients will use the correct URL. These changes imply updating the js\connection.js file. You have to update setConnection to:

function setConnection(host, port, urlPath)
{
  connectionInfo = {"host":host,"port":port,"authentication":null,"pathPrefix":urlPath};
  connectionInfo.dscontext = 'mycontext';
  connectionInfo.restcontext = 'myrest';
}

Response Numbers

Depending on the URI, exposed methods, execution results, the following codes are returned:


Code Reason Example

404

Datasnap keyword is missing from URI

http://my.site.com/rest

501

REST (or other protocol) keyword is missing

http://my.site.com/datasnap/x/y/z

501

Command type unrecognized

Other commands than GET, PUT, POST or DELETE

200

Execution successful

The response contains the output parameters {"result":[parameterValue[,parameterValue]*]}

201

PUT request was successful

The response contains the output parameters {"result":[parameterValue[,parameterValue]*]}

500

Method execution failed, reason incorporated in the response

-

Exposing a Server Method

Once the server class is registered with the DataSnap Server, any method should be HTTP callable if the signature allows it. If no user-defined mapping is provided, the server methods need to match the name convention above in order to be available for HTTP REST requests.

The parameters are mapped from the URI immediately after the server method name. If the number of parameters does not match or they are not input or input/output parameters, an error is returned.

See Also

Samples