Using the Worklist REST Service

This content applies to legacy components (such as K2 Studio and K2 for Visual Studio), legacy assemblies, legacy services or legacy functionality. If you have upgraded from K2 blackpearl 4.7 to K2 Five, these items may still be available in your environment. These legacy items may not be available in new installations of K2 Five. These legacy items may also not be available, supported, or behave as described, in future updates or versions of K2. Please see the legacy component support policy for more information about support for these components.

The Worklist REST Service supports two types of serialization namely XML and JSON.  To select the type of serialization, provide the appropriate Content-Type and Accept HTTP header values.

The following MIME types are supported:

  • application/xml
  • text/xml
  • application/json
  • text/json

In addition, versioning is supported and can be specified by appending a MIME parameter to the Content-Type or Accept HTTP headers. 

This topic is based on version 1.0 of the Worklist REST Service.

Content-Type

The Content-Type HTTP header is required for requests that support data payloads such as POST and PUT.  This indicates the serialization used for the request only.  For example:

Content-Type
application/xml

Accept

The Accept HTTP header must be provided for all requests. This indicates the serialization for the response body only.  For example:

Accept
application/xml

Versioning

It is recommended to specify a version on all requests.  If no version is specified, the latest version of the API will automatically be used.  This may however introduce breaking changes if your code is expecting a previous version schema.

Versioning Scheme

The versioning scheme is "<major>.<minor>". 

Increments in the major version may include substantial breaking changes. Increments in the minor version will not break compatibility.

Specifying the version

To specify the version add a "version" parameter to the Content-Type or Accept HTTP headers.  For example:

Content-Type
application/xml; version=1.0

Accept
application/xml; version=1 

Where no version is specified in the header, the latest major and minor versions will automatically be used.  If only the major version is specified, the latest minor version within the major version will automatically be used.  It is recommended to always supply a minor version.

Authentication

The Worklist REST Service supports both Windows and Basic authentication.  Basic authentication can be implemented as per the RFC 2617 standard.  However, due to the conflict of K2 labels and the colon character used in Basic authentication, the username must be passed to the Worklist REST Service in one of the following formats:

  • Option 1
    • <security label>\<domain>\<username>
      e.g.
      K2\DENALLIX\Bob
      or
      \DENALLIX\Bob
    • If no security label is specified, the default security label will be used.
  • Option 2
    • <security label>\<username>
      e.g.
      AAD\Bob@denallix.com
  • Option 3
    • <username>
      e.g.
      bob

Considerations

When using the Worklist REST Service, the PUT method behaves as a Merge instead of a Set on all endpoints.  This means that omitted data or fields will not be deleted, and data included will be updated.