URIs for Services

The sample code provided as a demonstration is written for use with Web based forms. Sample code for Windows based forms will be available in a future release of the Developer's Reference

URI Structure

{Service Root URI}{Service Path}?{Query Options}

Returns a collection of the first two Employees, starting with the tenth one, in XML format.

Service Root URI = {Scheme}{Server}:{Port}{Service Root}/{Service Type}
- Scheme = http:// or https:// if SSL is enabled
- Server = Server Name or Host Header of web site hosting K2 services
- Port = Port of web site hosting K2 SmartObject Services, the default is 8888
- Service Root = service endpoint exposed by K2 SmartObject Services. The default is:
- - /SmartObjectServices
- Service Type = /REST

The Service Root URI up to Service Type is configured via, the scheme, server, port and serviceroot settings in K2HostServer.exe.config.

Service Path = {CategoryPath}{SmartObjectName}{MethodName} – Identifies the SmartObject method to be interacted with, such as Employee Get List.
- CategoryPath = the path to the category that contains the SmartObject
- SmartObjectName = the display name of the SmartObject
- MethodName = the display name of the SmartObject method to execute

Query Options = {System Query Options }&{Custom Query Options}
- Multiple parameters can be combined using and & between them
- System Query Options – optional query string parameters that can be used to control the format and amount of data returned. The System Query Options start with a $ and are typically available for all URIs that return data. However $format parameter is only available for the list methods.
- - $format = xml (default), atom, or json
    Specifies the format to return the results. Uses default if omitted.
    https://api.denallix.com:8888/SmartObjectServices/REST/K2 Examples/Employee/Get List?$format=atom
  - Collection Options
  - - $skip = 0 (default), or N
      Specifies N number of records to skip. Uses 0 when omitted, which will return all records.
      https://api.denallix.com:8888/SmartObjectServices/REST/K2 Examples/Employee/Get List?$skip=2
  - $top = 0 (default), or N
    Specifies the first N records to retrieve. Uses 0 when omitted, which will return all records.
    https://api.denallix.com:8888/SmartObjectServices/REST/K2 Examples/Employee/Get List?$top=5
  - filterXml = {filterXml}
    Specifies the SmartObject filter to use to limit the results. Uses no filter when omitted, which will return all records. See the Filter section for more information.
    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>
- Custom Query Options – additional parameters specific to each SmartObject

Special Characters

K2 SmartObject Services utilizes standard URL escaping for URI construction.

%20 = {space} (standard URL escaping

Filter

K2 SmartObject Services utilizes the capabilities of the SmartObjects Filter Framework to enable filtering of your List based results for REST endpoints.

All SmartObject List methods will support the filterXml={filterXml} system query option via the REST endpoints.

The filterXml query option takes a single string parameter which is the filter represented as XML.

GET /SmartObjectServices/REST/K2%20Examples/Employee/Get%20List?filterXml=&lt;filterexp&gt;&lt;equals&gt;&lt;left&gt;&lt;propertyexp name="Last_Name" sotype="Text"/&gt;&lt;/left&gt;&lt;right&gt;&lt;valueexp sotype="Text"&gt;Cowan&lt;/valueexp&gt;&lt;/right&gt;&lt;/equals&gt;&lt;/filterexp&gt;

The filter XML can be created by hand or by using the SourceCode.SmartObjects.Client.Filter object to build up the filter and calling the GetFilterXml() method as outlined below.

Add a reference to SourceCode.SmartObjects.Client.dll
Add a using statement using SourceCode.SmartObjects.Client.Filters;
Use the object model to build the filter

static string BuildFilter() 
						{ 
						Equals lastNameEquals = new Equals(); 
						PropertyExpression lastNameExpression = new PropertyExpression("Last_Name", PropertyType.Text); 
						ValueExpression lastNameValue = new ValueExpression("Cowan", PropertyType.Text); 
						lastNameEquals.Left = lastNameExpression; 
						lastNameEquals.Right = lastNameValue; 

						// Serialize FilterExp filterExpression = new FilterExp(lastNameEquals); 
						XmlDocument filterXml = filterExpression.GetFilterXml(); 

						return filterXml.InnerXml; 
						}

The resulting XML for this BuildFilter() method would resemble the following:

<filterexp><equals><left><propertyexp name="Last_Name"

					sotype="Text"/></left><right><valueexp sotype="Text">Cowan</valueexp></right></equals></filterexp>

XML Return Example

GET /SmartObjectServices/rest/K2%20Examples/Employee/Get%20List?$format=xml&$skip=10&$top=2

						<ArrayOfEmployee xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> 
						<Employee> 
						<Id>11</Id> 
						<Username>DENALLIX\Rick</Username> 
						<First_Name>Rick</First_Name> 
						<Last_Name>Cowan</Last_Name> 
						<Email>rick@denallix.com</Email> 
						</Employee> 
						<Employee> 
						<Id>12</Id> 
						<Username>DENALLIX\Koos</Username> 
						<First_Name>Koos</First_Name> 
						<Last_Name>du Preez</Last_Name> 
						<Email>koos@denallix.com</Email> 
						</Employee> 
						</ArrayOfEmployee>

;

ATOM Return Example

GET /SmartObjectServices/rest/K2%20Examples/Employee/Get%20List?$format=atom&$skip=10&$top=2

						<feed xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns="http://www.w3.org/2005/Atom"> 
						<title type="text">K2 SmartObject Feed</title> 
						<subtitle type="text">K2 SmartObject Feed</subtitle> 
						<id>uuid:3c37d960-b60c-459f-9c9b-f65ede207107;id=1</id> 
						<updated>2011-02-17T18:27:40-07:00</updated> 
						<category term="Employee:GetList"/> 
						<author> 
						<name>K2 Server</name> 
						<uri>http://www.k2.com</uri> 
						<email>admin@k2.com</email> 
						</author> 
						<link rel="alternate" href="http://api.denallix.com:8888/SmartObjectServices/rest/K2%20Examples/Employee/Get%20List?$format=atom"/> 
						<entry> 
						<id>a6eacb3a-6a98-4cdc-8321-cd5544f91ae4</id> 
						<title type="text">Employee Row 1</title> 
						<summary type="text"/> 
						<updated>2011-02-17T18:27:40-07:00</updated> 
						<link rel="alternate" href="http://api.denallix.com:8888/SmartObjectServices/rest/K2%20Examples/Employee/Get%20List?$format=atom"/> 
						<content type="application/xml"> 
						<m:properties xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"> 
						<d:Id m:type="Edm.Int32">1</d:Id> 
						<d:Username m:type="Edm.String">DENALLIX\Rick</d:Username> 
						<d:First_Name m:type="Edm.String">Rick</d:First_Name> 
						<d:Last_Name m:type="Edm.String">Cowan</d:Last_Name> 
						<d:Email m:type="Edm.String">rick@denallix.com</d:Email> 
						</m:properties> 
						</content> 
						</entry> 
						<entry> 
						<id>c8eb486f-da64-45af-b48c-c69bd08480ec</id> 
						<title type="text">Employee Row 2</title> 
						<summary type="text"/> 
						<updated>2011-02-17T18:27:40-07:00</updated> 
						<link rel="alternate" href="http://api.denallix.com:8888/SmartObjectServices/rest/K2%20Examples/Employee/Get%20List?$format=atom"/> 
						<content type="application/xml"> 
						<m:properties xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"> 
						<d:Id m:type="Edm.Int32">2</d:Id> 
						<d:Username m:type="Edm.String">DENALLIX\Koos</d:Username> 
						<d:First_Name m:type="Edm.String">Koos</d:First_Name> 
						<d:Last_Name m:type="Edm.String">du Preez</d:Last_Name> 
						<d:Email m:type="Edm.String">koos@denallix.com</d:Email> 
						</m:properties> 
						</content> 
						</entry> 
						</feed>

ATOM Return Example

GET /SmartObjectServices/rest/K2%20Examples/Employee/Get%20List?$format=atom&$skip=10&$top=2

						<feed xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns="http://www.w3.org/2005/Atom"> 
						<title type="text">K2 SmartObject Feed</title> 
						<subtitle type="text">K2 SmartObject Feed</subtitle> 
						<id>uuid:3c37d960-b60c-459f-9c9b-f65ede207107;id=1</id> 
						<updated>2011-02-17T18:27:40-07:00</updated> 
						<category term="Employee:GetList"/> 
						<author> 
						<name>K2 Server</name> 
						<uri>http://www.k2.com</uri> 
						<email>admin@k2.com</email> 
						</author> 
						<link rel="alternate" href="http://api.denallix.com:8888/SmartObjectServices/rest/K2%20Examples/Employee/Get%20List?$format=atom"/> 
						<entry> 
						<id>a6eacb3a-6a98-4cdc-8321-cd5544f91ae4</id> 
						<title type="text">Employee Row 1</title> 
						<summary type="text"/> 
						<updated>2011-02-17T18:27:40-07:00</updated> 
						<link rel="alternate" href="http://api.denallix.com:8888/SmartObjectServices/rest/K2%20Examples/Employee/Get%20List?$format=atom"/> 
						<content type="application/xml"> 
						<m:properties xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"> 
						<d:Id m:type="Edm.Int32">1</d:Id> 
						<d:Username m:type="Edm.String">DENALLIX\Rick</d:Username> 
						<d:First_Name m:type="Edm.String">Rick</d:First_Name> 
						<d:Last_Name m:type="Edm.String">Cowan</d:Last_Name> 
						<d:Email m:type="Edm.String">rick@denallix.com</d:Email> 
						</m:properties> 
						</content> 
						</entry> 
						<entry> 
						<id>c8eb486f-da64-45af-b48c-c69bd08480ec</id> 
						<title type="text">Employee Row 2</title> 
						<summary type="text"/> 
						<updated>2011-02-17T18:27:40-07:00</updated> 
						<link rel="alternate" href="http://api.denallix.com:8888/SmartObjectServices/rest/K2%20Examples/Employee/Get%20List?$format=atom"/> 
						<content type="application/xml"> 
						<m:properties xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"> 
						<d:Id m:type="Edm.Int32">2</d:Id> 
						<d:Username m:type="Edm.String">DENALLIX\Koos</d:Username> 
						<d:First_Name m:type="Edm.String">Koos</d:First_Name> 
						<d:Last_Name m:type="Edm.String">du Preez</d:Last_Name> 
						<d:Email m:type="Edm.String">koos@denallix.com</d:Email> 
						</m:properties> 
						</content> 
						</entry> 
						</feed>

JSON Return Example

GET /SmartObjectServices/rest/K2%20Examples/Employee/Get%20List?$format=json&$skip=10&$top=2

						[{"Id":1,"Username":"DENALLIX\\Rick","First_Name":"Rick","Last_Name":"Cowan","Email":"rick@denallix.com"},{"Id":2,"Username":"DENALLIX\\Koos","First_Name":"Koos","Last_Name":"du Preez","Email":" koos@denallix.com"}]

Available Endpoints

K2 SmartObject Services makes it easy to determine all the available URIs for the system by providing them in an XML format. To see the available endpoints, navigate to:

{Scheme}{Server}:{Port}{Service Root}/endpoints/endpoints.xml.

Endpoints XML Example

A default installation of K2 blackpearl configured to generate endpoints for all system (out-of-the-box) SmartObjects produced this endpoints.xml (showing only REST endpoints).

GET /SmartObjectServices/endpoints/endpoints.xml

						<?xml version="1.0"?> 
						<endpoints> 
						<rest-endpoints> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Active Directory/AD User/Create</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Active Directory/AD User/Update?Name={Name}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Active Directory/AD User/Disable?Name={Name}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Active Directory/AD User/AddToGroups?Name={Name}&amp;Groups={Groups}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Active Directory/AD User/RemoveFromGroups?Name={Name}&amp;Groups={Groups}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Active Directory/AD User/RemoveFromAllGroups?Name={Name}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Active Directory/AD Group/Create</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Active Directory/AD Group/Update?Name={Name}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Active Directory/AD Group/Remove?Name={Name}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Active Directory/AD Group/AddMembers?Name={Name}&amp;Members={Members}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Active Directory/AD Group/RemoveMembers?Name={Name}&amp;Members={Members}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Exchange/Exchange Calendar/New Meeting</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Exchange/Exchange Calendar/New Appointment</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Exchange/Exchange Management/Enable Mailbox</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Exchange/Exchange Management/Disable Mailbox</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Exchange/Exchange Task/New Task</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Exchange/Exchange Meeting/Check Specific Time?$format={format}&amp;$top={top}&amp;$skip={skip}&amp;filterXml={filterXml}&amp;OnBehalfOf={OnBehalfOf}&amp;RequiredAttendees={RequiredAttendees}&amp;StartDateTimeFreeBusy={StartDateTimeFreeBusy}&amp;EndDateTimeFreeBusy={EndDateTimeFreeBusy}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Exchange/Exchange Meeting/Get Meeting Suggestions?$format={format}&amp;$top={top}&amp;$skip={skip}&amp;filterXml={filterXml}&amp;OnBehalfOf={OnBehalfOf}&amp;RequiredAttendees={RequiredAttendees}&amp;StartDateTimeFreeBusy={StartDateTimeFreeBusy}&amp;EndDateTimeFreeBusy={EndDateTimeFreeBusy}&amp;MeetingDurationMinutes={MeetingDurationMinutes}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Exchange/Exchange Metadata/Get Available Exchange Servers?$format={format}&amp;$top={top}&amp;$skip={skip}&amp;filterXml={filterXml}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Exchange/Exchange Metadata/Get Available Storage Groups?$format={format}&amp;$top={top}&amp;$skip={skip}&amp;filterXml={filterXml}&amp;ServerName={ServerName}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Exchange/Exchange Metadata/Get Available Mailbox Databases?$format={format}&amp;$top={top}&amp;$skip={skip}&amp;filterXml={filterXml}&amp;ServerName={ServerName}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Task Allocation/RoundRobinSO/Create</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Task Allocation/RoundRobinSO/Save?RoleName={RoleName}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Task Allocation/RoundRobinSO/Delete?RoleName={RoleName}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Task Allocation/RoundRobinSO/Load?RoleName={RoleName}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Task Allocation/RoundRobinSO/Get List?$format={format}&amp;$top={top}&amp;$skip={skip}&amp;filterXml={filterXml}&amp;RoleName={RoleName}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Task Allocation/TaskAllocationADMethods/Get Manager?UserName={UserName}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Task Allocation/TaskAllocationADMethods/Get Direct Reports?$format={format}&amp;$top={top}&amp;$skip={skip}&amp;filterXml={filterXml}&amp;UserName={UserName}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Task Allocation/TaskAllocationRoleMethods/Get Least Work?RoleName={RoleName}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Task Allocation/TaskAllocationRoleMethods/Get Most Work?RoleName={RoleName}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Task Allocation/TaskAllocationRoleMethods/Get Round Robin?RoleName={RoleName}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Task Allocation/TaskAllocationRoleMethods/Get Fastest User?RoleName={RoleName}&amp;MinTime={MinTime}&amp;MaxTime={MaxTime}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Task Allocation/TaskAllocationRoleMethods/Get Slowest User?RoleName={RoleName}&amp;MinTime={MinTime}&amp;MaxTime={MaxTime}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Task Allocation/TaskAllocationRoleMethods/Get Role Peers?$format={format}&amp;$top={top}&amp;$skip={skip}&amp;filterXml={filterXml}&amp;RoleName={RoleName}&amp;UserName={UserName}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Task Allocation/Users and Groups/Get E-mail For User?User_Fully_Qualified_Name={User_Fully_Qualified_Name}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Task Allocation/Users and Groups/Get E-mail For Group?Group_Fully_Qualified_Name={Group_Fully_Qualified_Name}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Task Allocation/Users and Groups/Get E-mail For Group Users?$format={format}&amp;$top={top}&amp;$skip={skip}&amp;filterXml={filterXml}&amp;Group_Fully_Qualified_Name={Group_Fully_Qualified_Name}&amp;User_Provider_Label={User_Provider_Label}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Task Allocation/Users and Groups/Get E-mail For Role Users?$format={format}&amp;$top={top}&amp;$skip={skip}&amp;filterXml={filterXml}&amp;Role_Name={Role_Name}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Workflow Reports/Workflow General/Process Instance/List?$format={format}&amp;$top={top}&amp;$skip={skip}&amp;filterXml={filterXml}&amp;ProcessInstanceID={ProcessInstanceID}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Workflow Reports/Workflow General/Activity Instance/List?$format={format}&amp;$top={top}&amp;$skip={skip}&amp;filterXml={filterXml}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Workflow Reports/Workflow General/Event Instance/List?$format={format}&amp;$top={top}&amp;$skip={skip}&amp;filterXml={filterXml}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Workflow Reports/Workflow General/Process Overview/List?$format={format}&amp;$top={top}&amp;$skip={skip}&amp;filterXml={filterXml}&amp;ProcessSetID={ProcessSetID}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Workflow Reports/Workflow General/Activity Data/List?$format={format}&amp;$top={top}&amp;$skip={skip}&amp;filterXml={filterXml}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Workflow Reports/Workflow General/Process Data/List?$format={format}&amp;$top={top}&amp;$skip={skip}&amp;filterXml={filterXml}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Workflow Reports/Workflow General/Process Definition/List Process Definitions?$format={format}&amp;$top={top}&amp;$skip={skip}&amp;filterXml={filterXml}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Workflow Reports/Workflow General/Process XML/List?$format={format}&amp;$top={top}&amp;$skip={skip}&amp;filterXml={filterXml}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Workflow Reports/Workflow General/Activity XML/List?$format={format}&amp;$top={top}&amp;$skip={skip}&amp;filterXml={filterXml}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Workflow Reports/Workflow General/Activity Slot Data/List?$format={format}&amp;$top={top}&amp;$skip={skip}&amp;filterXml={filterXml}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Workflow Reports/Workflow General/Activity Slot XML/List?$format={format}&amp;$top={top}&amp;$skip={skip}&amp;filterXml={filterXml}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Workflow Reports/Workflow General/Activity Instance Destination/List?$format={format}&amp;$top={top}&amp;$skip={skip}&amp;filterXml={filterXml}</endpoint> 
						<endpoint>http://api.denallix.com:8888/SmartObjectServices/rest/Workflow Reports/Workflow Solutions/K2Demo/ClaimsSample/ClaimsSample Process Instances/List Process Instances?$format={format}&amp;$top={top}&amp;$skip={skip}&amp;filterXml={filterXml}</endpoint> 
						</rest-endpoints> 
						</endpoints>

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

URIs for Services

URI Structure

Special Characters

Filter

XML Return Example

ATOM Return Example

ATOM Return Example

JSON Return Example

Available Endpoints

Endpoints XML Example

K2 BLACKPEARL PRODUCT DOCUMENTATION: DEVELOPER REFERENCE4.6.10