Request Filters

From RAD Studio
Jump to: navigation, search

Go Up to DataSnap REST


Within DataSnap, there is the concept of filtering results using request filters. These predefined filters connect into an API, which allows you to specify in the URL which filter to use for each parameter and what values to pass into the specific filter. For example, a server function may return a very large string, but you might only ever need the first few characters of it. For this you can use the SubString filter, specifying the range of the string you are interested in. Here is an example of how the URL would look like for a server function with a single input parameter and a string result:

http://localhost:8080/datasnap/rest/ClassName/FunctionName/ParamValue?ss.r=1,3

The parameter passed in as part of the URL says to use the range (r) function of the SubString (ss) request filter, with an offset of 1 (start with the second character) and a length of 3 (or Length(Result) - Offset, whichever is less.)

List of Request Filters

SubString (ss)

The SubString filter can be used for strings as well as streams, and has three different functions: count (c), offset (o), and range(r). All these functions work on both strings and streams, where they operate either on characters of a string or bytes of a stream.

Count takes a single parameter, which is the length of the substring you want (offset of zero).

Example that takes the first character of the result string: ss.c=1

Offset also takes a single parameter, which is the number of characters you want to skip in the substring.

Example that takes everything except the first character of the result string: ss.o=1

Range takes two parameters, the offset and the count, and acts like a regular SubString function.

Example that takes the second and third character of the result string: ss.r=1,2


Table (t)

The Table filter can be used on tables and makes use of the same functions as SubString: count (c), offset (o), and range (r).

Count represents how many rows to return, while Offset specifies how many rows to skip. Range, as with SubString, simply combines Offset and Count. An example using Range to return only the second and the third row of the result table is as follows:

http://localhost:8080/datasnap/rest/ClassName/FunctionName/ParamValue?t.r=1,3


Using Request Filters

The previous examples show the filter URL parameter syntax for applying a conversion (filter) to a returned value; however, you may want to apply conversions to in/out and output parameters as well. You can accomplish this by specifying the index of the parameter to transform.

Take, for example, a server function with the following signature:

function Echo( var Value: String ): String;

If you want to echo only the second and third characters of the input string, you can do this as shown in the previous example, by converting the result like this:

http://localhost:8080/datasnap/rest/ClassName/Echo/Hello?ss.r=1,3	(Result: ell)

Or instead, you can apply the conversion on the var parameter that is to be echoed:

http://localhost:8080/datasnap/rest/ClassName/Echo/Hello?ss0.r=1,3 	(Result: Hello)

Note: Request filters for parameters are executed after the function call, so to retrieve the converted result in this example, you must take the JSON result and get the object at array index 0. (As opposed to getting the result, which is always the last value in the array.)

The difference between the two is that the first just uses ss, which indicates to use the request filter on the function result, while the second example uses ss0, which indicates to use the filter on the function signature’s parameter at index 0.

You can specify multiple URL parameters to use multiple request filters. Take this server function for example:

Function ClassName.Echo( var Value1, Value2: String ): String
begin
   Result := Value1 + Value2;
end;

The following function will take in two parameters, append them, and return the result. Calling this function with no request filters looks like:

http://localhost:8080/datasnap/rest/ClassName/Echo/Hello/World		(Result: HelloWorld)

You can use request filters on both the parameters, in any of the given ways. Note that the result will remain the same--“HelloWorld”:

http://localhost:8080/datasnap/rest/ClassName/Echo/Hello/World?ss0,1.c=1
http://localhost:8080/datasnap/rest/ClassName/Echo/Hello/World?ss0-1.c=1
http://localhost:8080/datasnap/rest/ClassName/Echo/Hello/World?ss0.c=1& ss1.c=1

For each of the previous examples, the JSON result will contain an array of three values. The first value is “H”, the second value--“W”, and the third value--the result: “HelloWorld.”