URIs for Services

URI Structure

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

1

Returns a collection of the first five users, starting with the tenth one, in XML format.

  • Service Root URI = {Scheme}{Server}:{Port}{Service Root}
    • Scheme = http:// or https:// if SSL is enabled (default)
    • Server = Server Name or Host Header of web site hosting K2 services
    • Port = Port of web site hosting K2 Services
    • Service Root = Virtual directory and service endpoint exposed by K2 Services.  The values for Service Root are configurable.  The defaults are:
      •  /K2Services/REST.svc
      •  /K2Services/SyncREST.svc
    • Service Path – Identifies the service to be interacted with, such as Process Instance, Worklist, Task, Identities and Core.  The service paths that are made available can be configured for each Service Root URI.

Service Paths are case sensitive.

  • Query Options = {System Query Options }&{Custom Query Options}
    • Multiple parameters can be combined using an & 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.
      • $format = xml (default), atom, or json
        Specifies the format to return the results.  Uses default if omitted.
        https://api.denallix.com:443/K2Services/REST.svc/Identity/Users?$format=atom

POST data will be deserialized according to the Content-type specified in the Request Header.  The response from the server will be serialized according to the $format tag, or the Content-type if the $format tag is omitted.

  • 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:443/K2Services/REST.svc/Identity/Users?$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:443/K2Services/REST.svc/ Identity/Users?$top=5
  • Custom Query Options – additional parameters specific to each service. These are not case sensitive.

Replacement Characters

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.

  •  _U_ = _ (Underscore)
  •  _S_ = / (Forward Slash)
  •  _B_ = \ (Backslash)
  •  _C_ = : (Colon)
  • %20 = {space} (standard URL escaping)

Examples

XML Return Example

GET /K2Services/REST.svc/Identity/Users?$format=xml&$skip=10&$top=2

<?xml version="1.0" encoding="utf-8"?>
<UserCollection xmlns="http://schemas.k2.com/user/d1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 <User Username="DENALLIX\Brandon" Fqn="K2:DENALLIX\Brandon" Email="Brandon@denallix.com" Manager="DENALLIX\Erica" DisplayName="Brandon Brown"/>
 <User Username="DENALLIX\Mark" Fqn="K2:DENALLIX\Mark" Email="Mark@denallix.com" Manager="DENALLIX\Erica" DisplayName="Mark Green"/>
</UserCollection>

ATOM Return Example

GET /K2Services/REST.svc/Identity/Users?$format=atom&$skip=10&$top=2

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
 <title type="text">Users</title>
 <subtitle type="text">Users</subtitle>
 <id>uuid:1c0d7d3f-b0e1-4162-999b-3fe2092c63d4;id=1</id>
 <updated>2011-02-14T07:45:00-07:00</updated>
 <category term="Identity"/>
 <link rel="alternate" href="https://api.denallix.com:443/K2Services/REST.svc/Identity/Users?$format=atom&amp;$skip=10&amp;$top=2"/>
 <entry>
  <id>K2:DENALLIX\Brandon</id>
  <title type="text">Brandon Brown</title>
  <summary type="text">
   Username = DENALLIX\Brandon&#xD;
   Fqn = K2:DENALLIX\Brandon&#xD;
   Email = Brandon@denallix.com&#xD;
   Manager = DENALLIX\Erica&#xD;
   DisplayName = DENALLIX\Erica&#xD;
  </summary>
  <published>2011-02-14T07:45:00-07:00</published>
  <updated>2011-02-14T07:45:00-07:00</updated>
  <link href="https://api.denallix.com:443/K2Services/REST.svc/Identity/Users?$format=atom&amp;$skip=10&amp;$top=2"/>
  <content type="application/xml">
   <User xmlns="http://schemas.k2.com/user/d1" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <DisplayName>Brandon Brown</DisplayName>
    <Email>Brandon@denallix.com</Email>
    <Fqn>K2:DENALLIX\Brandon</Fqn>
    <Manager>DENALLIX\Erica</Manager>
    <Properties i:nil="true"/>
    <Username>DENALLIX\Brandon</Username>
   </User>
  </content>
 </entry>
 <entry>
  <id>K2:DENALLIX\Mark</id>
  <title type="text">Mark Green</title>
  <summary type="text">
   Username = DENALLIX\Mark&#xD;
   Fqn = K2:DENALLIX\Mark&#xD;
   Email = Mark@denallix.com&#xD
   Manager = DENALLIX\Erica&#xD;
   DisplayName = DENALLIX\Erica&#xD;
  </summary>
  <published>2011-02-14T07:45:00-07:00</published>
  <updated>2011-02-14T07:45:00-07:00</updated>
  <link href="https://api.denallix.com:443/K2Services/REST.svc/Identity/Users?$format=atom&amp;$skip=10&amp;$top=2"/>
  <content type="application/xml">
   <User xmlns="http://schemas.k2.com/user/d1" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <DisplayName>Mark Green</DisplayName>
    <Email>Mark@denallix.com</Email>
    <Fqn>K2:DENALLIX\Mark</Fqn>
    <Manager>DENALLIX\Erica</Manager>
    <Properties i:nil="true"/>
    <Username>DENALLIX\Mark</Username>
   </User>
  </content>
 </entry>
</feed>

JSON Return Example

GET /K2Services/REST.svc/Identity/Users?$format=json&$skip=10&$top=2

[{"DisplayName":"Brandon Brown","Email":"Brandon@denallix.com","Fqn":"K2:DENALLIX\\Brandon","Manager":"DENALLIX\\Erica","Properties":null,"Username":"DENALLIX\\Brandon"},{"DisplayName":"Mark Green","Email":"Mark@denallix.com","Fqn":"K2:DENALLIX\\Mark","Manager":"DENALLIX\\Erica","Properties":null,"Username":"DENALLIX\\Mark"}]

Filter XML Request Body Example

<?xml version="1.0" encoding="utf-8"?>
<Criteria xmlns="http://schemas.k2.com/worklist/d1">
  <Filter Field="ProcessFolio" Comparison="Like" ValueType="String">Demo</Filter>
  <Sort Field="ProcessStartDate" Order="Descending" />
</Criteria>