RESTful services expose each method of a SmartObject as a separate endpoint. This means you will access the methods by submitting requests to a specific URI, and include query string parameters to specify how and what data is returned.
The basic URI of these services is as follows:
{Service Root URI}{Service Path}?{Query Options}
The image below illustrates how a REST service endpoint is constructed:
As with the WCF services, the Service Root URI is defined by the <smoServices> section of the K2HostServer.exe.config file. The Service Path is defined by the SmartObject’s location in the category system (or by the Alias value specified in the K2HostServer.exe.config file) and each method for the SmartObject is appended to the service path to create separate endpoints for each SmartObject method.
To prevent the need for double escaping, K2 accepts the following replacement characters when passed as part of the Service Path. There is no need to use replacement characters when passing values as Query Options.
Structure: {Scheme}{Server}:{Port}{Service Root}/{Service Type}
This part is the "root" URL that exposes the various, SmartObject-specific endpoints.
The Service Root URI (up to Service Type) is configured via the scheme, server, port and serviceroot settings in K2HostServer.exe.config.
Structure: {CategoryPath}{SmartObjectName}{MethodName}
This part identifies the SmartObject and the SmartObject method being targeted.
The Service Path is inferred by K2 through the location of the SmartObject in the Category System, the SmartObjects' display name and the SmartObject Method Display Name.
The query options are used to provide values for the parameters expected by the SmartObject method, to pass in filter expressions or, in the case of list methods, to specify the return format of the data. Multiple parameters can be combined using & between the parameters.
Structure:?{System Query Options }&{Custom Query Options}
System Query Options are query string parameters that can be used to control the format and amount of data returned. System Query Options start with a $ and are typically available for all URIs that return data.
Query Option | Values/Sample Values | Notes |
---|---|---|
$format |
xml atom json |
Specifies the format to return the results. Uses default (XML) if omitted. The $format parameter is only available for List methods Example: https://api.denallix.com:8888/SmartObjectServices/REST/K2 Examples/Employee/Get List?$format=atom |
$skip | Integer, e.g. 0 (default), or N | Specifies N number of records to skip. Uses 0 when omitted, which will return all records. The $skip parameter is only available for List methods Example: https://api.denallix.com:8888/SmartObjectServices/REST/K2 Examples/Employee/Get List?$skip=2 |
$top | Integer, e.g. 0 (default), or N | Specifies the first N records to retrieve. Uses 0 when omitted, which will return all records The $top parameter is only available for List methods Example: https://api.denallix.com:8888/SmartObjectServices/REST/K2 Examples/Employee/Get List?$top=5 |
$ filterXml | An XML string representing the filter to apply to the method results. | Specifies the SmartObject filter to use to limit the results. Uses no filter when omitted, which will return all records. The $filterXml parameter is only available for List methods Example: https://api.denallix.com:8888/SmartObjectServices/REST/K2 Examples/Employee/Get List?filterXml=<filterexp><equals><left><propertyexp name="Last_Name" sotype="Text"/></left><right><valueexp sotype="Text">Cowan</valueexp></right></equals></filterexp> |
K2 SmartObject Services utilizes the capabilities of the SmartObjects Filter Framework to enable filtering of your List based results for REST endpoints. The filterXml query option takes a single string parameter which is the filter represented as XML.
Below is an example of a filterXML value where we defined a filter to return only Employees where the Last_Name property is equal to "Cowan":
You can create the filter XML by hand, or use the SourceCode.SmartObjects.Client.Filter object in the SourceCode.SmartObject.Client.dll assembly to build up the filter and calling the GetFilterXml() method. This is also a useful approach if you want to obtain a sample XML string to begin with and then extend on further with manual editing.
The resulting XML for this method would resemble the following (formatted for clarity, if you were to pass this filter in, this value would be one long line of XML:
You can build the XML string with the SmartObject Services Tester Tool ([Program Files (x86)]\K2 blackpearl\Bin\SmartObject Service Tester.exe).Execute a SmartObject that has a list method. In the List Method Options, click the Set button in the Filter section to open the SmartObject Filter dialog.
Build your filter and then copy the XML representation of the filter to a text editor. Edit the XML and make sure you remove line breaks so that it’s a single line, and then add the <filterexp></filterexp> container tags as shown in these samples:
Comparison Operators and Functions.
Equals
Greater Than
Less Than
StartsWith
EndsWith
Contains
IsNull
Logical Operators
And
Or
Not
Expressions
PropertyExpression
ValueExpression
Video | Links | Learn | Support |
No videos found for this article K2 on YouTube
No Additional links found for this article
No self-learning content for this article Try some scenarios...
No relevant support links available for this article
|