Interfacing with the iTasks JSON API

From Clean
Jump to navigationJump to search

The primary way an iTasks application interacts with the outside world is through REST-style JSON webservices. The default Ajax client for end users uses this interface, but it may also be used to interact with other systems.

Design Overview

The interface is a set of REST-style webservices. This means that a part of the server's state is mapped to a set of (dynamic) documents with meaningful URLs. We use JSON as the encoding of these documents because it is easily printable/parsable in many languages and works particularly well with Javascript. Interaction with the server is done through posting parameters to these documents.

All JSON services are accessible at URLs that start with "/services/json/". For debugging the services are also available with a very basic html interface at "/services/html". The JSON structures are then pretty printed and a form is given for entering parameters. In the remainder of this document we use the "/services/json/" URLs, but you may always substitute "json" for "html".

An iTask server offers the following services:

  • Authentication and session management at "/services/json/sessions"
  • A workflow catalogue at "/services/json/workflows"
  • Listing of and interaction with active tasks at "/services/json/tasks"
  • Listing of system users at "/services/json/users"
  • Uploading/downloading of documents at "/services/json/documents"
  • Application meta-data at "/services/json/application"

The Services in Detail

Authentication service

Workflow catalogue service

Task service

User service

Document service

Application service