= Taskana RESTful API Documentation taskana.pro; :doctype: book :icons: font :source-highlighter: highlightjs :toc: left :toclevels: 4 :sectlinks: = Overview [big]#*This Documentation is still under development and probably incomplete and/or flawed in certain areas.*# == HTTP verbs The Taskana RESTful API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs. |=== | Verb | Usage | `GET` | Used to retrieve a resource | `POST` | Used to create a new resource | `PUT` | Used to update a resource | `DELTE` | Used to delete a existing resource |=== == HTTP status codes The Taskana RESTful API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes. |=== | Status code | Usage | `200 OK` | The request completed successfully. | `201 Created` | The request completed successfully und create the new resource. | `202 Accepted` | The request could not be processed immediatly but will be carried out later. | `204 No Content` | The request completed successfully and there is no content to send in the response payload. | `400 Bad Request` | The request was not performed because of a client error like a invalid parameter. | `401 Unauthorized` | The request has not been applied because it lacks valid authentication credentials for the target resource. | `403 FORBIDDEN` | The current user has no read permission for . | `404 Not Found` | The requested resource did not exist. | `405 Method not allowed` | The method used in this request is can not be used on this resource. | `406` Not acceptable | Wrong content-type in request header. | `409 Conflict` | The resource could not be updatet or created because of a conflict with an existing one. | `415 Unsupported Media Type` | The content of the request can't be understood due to being in an unsupported media-type. | `423 Locked` | The resource is currently locked and cannot be modified. |=== == Common Fields Taskana uses Spring HATEOAS to achive the best possible REST-conformity. + In HATEOAS every response contains a map named *_links* in which the links for navigation are included. + If a resource has embedded resources these are found in a map named *_embedded*. === Response Fields common to all Resources Every Resource contains at least the link to itself. include::{snippets}/CommonFields/response-fields.adoc[] === Response Fields common to all Summary Resources Summary Resources contain embedded resources and can be requested in a <>. include::{snippets}/CommonSummaryResourceFields/response-fields.adoc[] == Tasks-Resource === Get a list of all tasks A `GET` request is used to retrieve a task summary. ==== Example Request include::{snippets}/GetAllTasksDocTest/http-request.adoc[] ==== Example Response include::{snippets}/GetAllTasksDocTest/http-response.adoc[] ==== Response Structure include::{snippets}/GetAllTasksDocTest/response-fields.adoc[] === Filter and sort options The list generated in the response can be filtered using following parameters in the uri: + name | priority | state | classification.key | workbasket-id | {workbasket-key , domain} | + owner | por.company | por.system | por.instance | por.type | por.value + planned | planned-from | planned-until | due | due-from | due-until | + external-id | wildcard-search-value | wildcard-search-fields When filtering a wildcard search you must provide both paremters + (wildcard-search-value and wildcard-search-fields). Valid wildcard-search-fields are: + -name + -description + -custom_1 to custom_16 + These fields are case insensitive! + If it is sufficient to filter the list with a single time interval, use the parameters + planned-from/due-from and planned-until/due-until. + Leave one of them out of the request, if you want to have an open interval. + If it is required to filter the list with multiple planned or due time intervals, the parameters + planned / due can be used as follows instead: + - provide a string with an even number of instants separated by a ",". Time intervals will be + determined in pairs of those instants. + - in case of a required open interval, just give one of the arguments of the pair an empty string + like this: + planned = {Instant1},{Instant2},,{Instant3} this will create two intervals, one between Instant1 + and Instant2 as well as an open interval between the beginning of time and Instant3 + Note that it is prohibited to use the planned / due parameter in combination with the + planned-from/due-from and/or planned-until/due-until parameters + It can also be sorted by using this set of parameters: + sortBy = { classification.key | por.type | por.value | state | name| due | planned | priority } | order={ desc | asc } === Get a single task A `GET` request is used to retrieve a task. ==== Example Request include::{snippets}/GetSpecificTaskDocTest/http-request.adoc[] ==== Example Response include::{snippets}/GetSpecificTaskDocTest/http-response.adoc[] [[task]] ==== Response Structure include::{snippets}/GetSpecificTaskDocTest/response-fields.adoc[] === Update a task A `PUT` request is used to update a task. ==== Example Request include::{snippets}/UpdateTaskDocTest/http-request.adoc[] ==== Request Structure include::{snippets}/UpdateTaskDocTest/request-fields.adoc[] ==== Example Response include::{snippets}/UpdateTaskDocTest/http-response.adoc[] ==== Response Structure include::{snippets}/UpdateTaskDocTest/response-fields.adoc[] === Claim a task A `POST` request is used to claim a task ==== Example Request Note the empty request-body in the example. include::{snippets}/ClaimTaskDocTest/http-request.adoc[] ==== Example Response include::{snippets}/ClaimTaskDocTest/http-response.adoc[] ==== Response Structure The response-body is essentially the same as for getting a single task. + Therefore for the response fields you can refer to the <>. === Cancel Claim a task A `DELETE` request is used to cancel claim a task ==== Example Request Note the empty request-body in the example. include::{snippets}/CancelClaimTaskDocTest/http-request.adoc[] ==== Example Response include::{snippets}/CancelClaimTaskDocTest/http-response.adoc[] ==== Response Structure The response-body is essentially the same as for getting a single task. + Therefore for the response fields you can refer to the <>. === Select and Claim a task A `POST` request is used to select and claim a task ==== Example Request Note the empty request-body in the example. include::{snippets}/SelectAndClaimTaskDocTest/http-request.adoc[] ==== Example Response include::{snippets}/SelectAndClaimTaskDocTest/http-response.adoc[] ==== Response Structure The response-body is essentially the same as for getting a single task. + Therefore for the response fields you can refer to the <>. === Complete a task A `POST` request is used to complete a task ==== Example Request Note the empty request-body in the example. include::{snippets}/CompleteTaskDocTest/http-request.adoc[] ==== Example Response include::{snippets}/CompleteTaskDocTest/http-response.adoc[] ==== Response Structure The response-body is essentially the same as for getting a single task. + Therefore for the response fields you can refer to the <>. === Create a new task A `POST` request is used to create a new task. ==== Example Request This minimal example shows only the required fields to create a new task. The <> shows all possible fields for creating a task. include::{snippets}/CreateTaskDocTest/http-request.adoc[] [[create-task-request-structure, request structure]] ==== Request Structure include::{snippets}/CreateTaskDocTest/request-fields.adoc[] ==== Example Response include::{snippets}/CreateTaskDocTest/http-response.adoc[] ==== Response Structure The response-body is essentially the same as for getting a single task. + Therefore for the response fields you can refer to the <>. === Delete a task A `DELETE` request is used to delete a task. ==== Example request include::{snippets}/DeleteTaskDocTest/http-request.adoc[] ==== Example response include::{snippets}/DeleteTaskDocTest/http-response.adoc[] === Delete multiple tasks A `DELETE` request is used to delete multiple tasks. ==== Example request include::{snippets}/DeleteTasksDocTest/http-request.adoc[] ==== Example response include::{snippets}/DeleteTasksDocTest/http-response.adoc[] === Transfer a task to another workbasket A `POST` request is used to transfer a task from one to another workbasket. ==== Example Request include::{snippets}/TransferTaskDocTest/http-request.adoc[] ==== Example Response include::{snippets}/TransferTaskDocTest/http-response.adoc[] ==== Response Structure The response-body is essentially the same as for getting a single task. + Therefore for the response fields you can refer to the <>. == TaskComment-Resource === Get a list of all task comments for a specific task A `GET` request is used to retrieve the task comments. ==== Example Request include::{snippets}/GetAllTaskCommentsForSpecificTaskDocTest/http-request.adoc[] ==== Example Response include::{snippets}/GetAllTaskCommentsForSpecificTaskDocTest/http-response.adoc[] ==== Response Structure include::{snippets}/GetAllTaskCommentsForSpecificTaskDocTest/response-fields.adoc[] === Sort options sort-by={ created | modified } | order={ desc | asc } === Get a specific task comment A `GET` request is used to retrieve a task comment. ==== Example Request include::{snippets}/GetSpecificTaskCommentDocTest/http-request.adoc[] ==== Example Response include::{snippets}/GetSpecificTaskCommentDocTest/http-response.adoc[] ==== Response Structure include::{snippets}/GetSpecificTaskCommentDocTest/response-fields.adoc[] === Update a task comment A `PUT` request is used to update a task comment. ==== Example Request include::{snippets}/UpdateTaskCommentDocTest/http-request.adoc[] ==== Request Structure include::{snippets}/UpdateTaskCommentDocTest/request-fields.adoc[] ==== Example Response include::{snippets}/UpdateTaskCommentDocTest/http-response.adoc[] ==== Response Structure include::{snippets}/UpdateTaskCommentDocTest/response-fields.adoc[] === Create a new task comment A `POST` request is used to create a new task comment. ==== Example Request This minimal example shows only the required fields to create a new task comment. The <> shows all possible fields for creating a task comment. include::{snippets}/CreateTaskCommentDocTest/http-request.adoc[] [[create-taskcomment--request-structure, request structure]] ==== Request Structure include::{snippets}/CreateTaskCommentDocTest/request-fields.adoc[] ==== Example Response include::{snippets}/CreateTaskCommentDocTest/http-response.adoc[] ==== Response Structure The response-body is essentially the same as for getting a specific task comment. + Therefore for the response fields you can refer to the <>. === Delete a task comment A `DELETE` request is used to delete a task comment. ==== Example request include::{snippets}/DeleteTaskCommentDocTest/http-request.adoc[] ==== Example response include::{snippets}/DeleteTaskCommentDocTest/http-response.adoc[] == Classifications-Resource This resource provides the entry point with classifications. === Get a list of all classifications A `GET` request is used to retrieve a classification summary. ==== Example Request include::{snippets}/GetAllClassificationsDocTest/http-request.adoc[] ==== Example Response include::{snippets}/GetAllClassificationsDocTest/http-response.adoc[] ==== Response Structure include::{snippets}/GetAllClassificationsDocTest/response-fields.adoc[] The response-body is essentially the same as for getting a single classification. + Therefore for the response fields you can refer to the structure of the <>. ==== Example Request === Filter and sort options The list generated in the response can be filtered using following parameters in the uri: + name | name-like | key | category | domain | type | custom-{1...8}-like + It can also be sorted by using this set of parameters: + sortBy = {category | domain | key | name } | order={desc | asc } === Get a single classification A `GET` request is used to retrieve a classification. ==== Example Request include::{snippets}/GetSpecificClassificationDocTest/http-request.adoc[] ==== Example Response include::{snippets}/GetSpecificClassificationDocTest/http-response.adoc[] [[classification]] ==== Response Structure include::{snippets}/GetSpecificClassificationDocTest/response-fields.adoc[] === Update a Classification A `PUT` request is used to update a classification. ==== Example Request include::{snippets}/UpdateClassificationDocTest/http-request.adoc[] ==== Request Structure The request-body is essentially the same as for getting a single classification. + Therefore for the request fields you can refer to the structure of the <>. ==== Example Response include::{snippets}/UpdateClassificationDocTest/http-response.adoc[] ==== Response Structure The response-body is essentially the same as for getting a single classification. + Therefore for the response fields you can refer to the structure of the <>. === Create a new Classification A `POST` request is used to create a new classification. ==== Example Request This minimal example shows only the required fields to create a new classification. The <> shows all possible fields for creating a classification. include::{snippets}/CreateClassificationDocTest/http-request.adoc[] [[create-classification-request-structure]] ==== Request Structure include::{snippets}/CreateClassificationDocTest/request-fields.adoc[] ==== Example Response include::{snippets}/CreateClassificationDocTest/http-response.adoc[] ==== Response Structure The response-body is essentially the same as for getting a single classification. + Therefore for the response fields you can refer to the structure of the <>. === Delete a classification A `DELETE` request is used to delete a classification. ==== Example Request include::{snippets}/DeleteClassificationDocTest/http-request.adoc[] ==== Example Response include::{snippets}/DeleteClassificationDocTest/http-response.adoc[] == Classification-definition-Resource [[classification-definitions]] === Get all classification definitions A `GET` request is used to get all classification definitions. ==== Example Request include::{snippets}/ExportClassificationDefinitionsDocTest/http-request.adoc[] ==== Example Response include::{snippets}/ExportClassificationDefinitionsDocTest/http-response.adoc[] ==== Response Structure include::{snippets}/ExportClassificationDefinitionsDocTest/response-fields.adoc[] === Import new classification-definitions A `POST` request is used to import new classification-definitions. ==== Example Request This minimal example shows only the required fields to import a single new classification-definition. The <> shows all possible fields for importing (and therefore creating) new classification-definitions. include::{snippets}/ImportClassificationDefinitions/http-request.adoc[] ==== Example Response include::{snippets}/ImportClassificationDefinitions/http-response.adoc[] == Workbaskets-Resource === Get a list of all workbaskets A `GET` request is used to retrieve a workbasket summary. ==== Example Request include::{snippets}/GetAllWorkbasketsDocTest/http-request.adoc[] ==== Example Response include::{snippets}/GetAllWorkbasketsDocTest/http-response.adoc[] ==== Response Structure include::{snippets}/GetAllWorkbasketsDocTest/response-fields.adoc[] === Filter and sort options The list generated in the response can be filtered using following parameters in the uri: + name | name-like | key | key-like | owner | owner-like | description-like | domain | + type={GROUP | PERSONAL | TOPIC | CLEARANCE} | + required-permission={READ|OPEN|APPEND|TRANSFER|DISTRIBUTE|CUSTOM_1...12} + It can also be sorted by using this set of parameters: + sortBy = {key | name | owner | type } | order={desc | asc } === Get a single workbasket A `GET` request is used to retrieve a workbasket. ==== Example Request include::{snippets}/GetSpecificWorkbasketDocTest/http-request.adoc[] ==== Example Response include::{snippets}/GetSpecificWorkbasketDocTest/http-response.adoc[] [[workbasket]] ==== Response Structure include::{snippets}/GetSpecificWorkbasketDocTest/response-fields.adoc[] === Update a workbasket A `PUT` request is used to update a workbasket ==== Example Request include::{snippets}/UpdateWorkbasketDocTest/http-request.adoc[] ==== Request Structure The request-body is essentially the same as for getting a single workbasket. + Therefore for the request fields you can refer to the structure of the <>. ==== Example Response include::{snippets}/UpdateWorkbasketDocTest/http-response.adoc[] ==== Response Structure The response-body is essentially the same as for getting a single workbasket. + Therefore for the response fields you can refer to the structure of the <>. === Delete workbasket A `DELETE` request to delete a workbasket. Since workbaskets can contain completed and non-completed task, the request has different response codes: + - *204 NO_CONTENT* - Workbasket has been deleted successfully - *202 ACCEPTED* - Workbasket still contains completed tasks. It has been marked for deletion and will be deleted automatically as soon as all completed tasks are deleted. - *423 LOCKED* - Worbasket contains non-completed tasks and cannot be deleted. ==== Example Request include::{snippets}/DeleteWorkbasketDocTest/http-request.adoc[] ==== Example Response include::{snippets}/DeleteWorkbasketDocTest/http-response.adoc[] === Remove a workbasket as distribution-target A `DELETE` request is used to remove a workbasket as a distribution-taregt. ==== Example Request include::{snippets}/RemoveWorkbasketAsDistributionTargetDocTest/http-request.adoc[] ==== Example Response include::{snippets}/RemoveWorkbasketAsDistributionTargetDocTest/http-response.adoc[] === Get all Access-Items for a workbasket A `GET` request is used to get a list of all accessitems of a workbasket. ==== Example Request include::{snippets}/GetAllWorkbasketAccessItemsDocTest/http-request.adoc[] ==== Example Response include::{snippets}/GetAllWorkbasketAccessItemsDocTest/http-response.adoc[] ==== Response Structure include::{snippets}/GetAllWorkbasketAccessItemsDocTest/response-fields.adoc[] === Get all distribution-targets for a workbasket A `GET` request is used to get a list of the distribution-targets of a workbasket. ==== Example Request include::{snippets}/GetAllWorkbasketDistributionTargets/http-request.adoc[] ==== Example Response include::{snippets}/GetAllWorkbasketDistributionTargets/http-response.adoc[] ==== Response Structure include::{snippets}/GetAllWorkbasketDistributionTargets/response-fields.adoc[] === Create a new Workbasket A `POST` request is used to create a new workbasket. ==== Example Request This minimal example shows only the required fields to create a new workbasket. The <> shows all possible fields for creating a workbasket. include::{snippets}/CreateWorkbasketDocTest/http-request.adoc[] [[create-workbasket-request-structure]] ==== Request Structure include::{snippets}/CreateWorkbasketDocTest/request-fields.adoc[] ==== Example Response include::{snippets}/CreateWorkbasketDocTest/http-response.adoc[] ==== Response Structure The response-body is essentially the same as for getting a single classification. + Therefore for the response fields you can refer to the structure of the <>. == Workbasket-definition-resource === Get all workbasket definitions A `GET` request is used to get all workbasket definitions. ==== Example Request include::{snippets}/ExportWorkbasketdefinitionsDocTest/http-request.adoc[] ==== Example Response include::{snippets}/ExportWorkbasketdefinitionsDocTest/http-response.adoc[] [[workbasket-definitions]] ==== Response Structure include::{snippets}/ExportWorkbasketdefinitionsDocTest/response-fields.adoc[] === Import new workbasket-definitions A `POST` request is used to import new workbasket-definitions. ==== Example Request This minimal example shows only the required fields to import a single new workbasket-definition. The <> shows all possible fields for importing (and therefore creating) new workbasket-definitions. include::{snippets}/ImportWorkbasketDefinitions/http-request.adoc[] ==== Response Structure include::{snippets}/ImportWorkbasketDefinitions/http-response.adoc[] == WorkbasketAccessItems-Resource === GET a list of all workbasketAccessItems A `GET` return all workbasketAccessItems that correspond the given data. ==== Example Request include::{snippets}/GetWorkbasketAccessItemsDocTest/http-request.adoc[] ==== Example Response include::{snippets}/GetWorkbasketAccessItemsDocTest/http-response.adoc[] ==== Response Structure include::{snippets}/GetWorkbasketAccessItemsDocTest/response-fields.adoc[] === Filter and sort options The list generated in the response can be filtered using following parameters in the uri: + workbasket-key | workbasket-key-like | access-id | access-id-like + name | name-like | key | key-like | owner | owner-like | description-like | domain | + It can also be sorted by using this set of parameters: + sortBy = { workbasket-key | access-id } | order={ desc | asc } === Delete a workbasketAccessItems A `DELETE` request is used to delete a workbasketAccessItems. ==== Example request include::{snippets}/RemoveWorkbasketAccessItemsDocTest/http-request.adoc[] ==== Example response include::{snippets}/RemoveWorkbasketAccessItemsDocTest/http-response.adoc[] == Monitor-Resource === Get a task status report A `GET` request is used to get a task status report. ==== Example Request include::{snippets}/GetTaskStatusReportDocTest/http-request.adoc[] ==== Example Response include::{snippets}/GetTaskStatusReportDocTest/http-response.adoc[] ==== Response Structure include::{snippets}/GetTaskStatusReportDocTest/response-fields.adoc[] === Get a tasks workbasket report A `GET` request is used to get the number of tasks sorted by state. ==== Example Request include::{snippets}/GetTaskWorkbasketReportDocTest/http-request.adoc[] ==== Example Response include::{snippets}/GetTaskWorkbasketReportDocTest/http-response.adoc[] ==== Response Structure Same as task status report === Get a tasks classification report A `GET` request is used to get the number of tasks sorted by state. ==== Example Request include::{snippets}/GetTaskClassificationReportDocTest/http-request.adoc[] ==== Example Response include::{snippets}/GetTaskClassificationReportDocTest/http-response.adoc[] ==== Response Structure Same as task status report === Get a timestamp report A `GET` request is used to get the number of tasks sorted by a task timestamp. ==== Example Request include::{snippets}/GetTimestampReportDocTest/http-request.adoc[] ==== Example Response include::{snippets}/GetTimestampReportDocTest/http-response.adoc[] ==== Response Structure Same as task status report == Other Resources (using the TaskanaEngineController) These resources are directly connected to the Taskana Engine endpoint. === Domains-Resource This resource provides information which Domains exist in the system. ==== Example Request include::{snippets}/GetAllDomainsDocTest/http-request.adoc[] ==== Example Response include::{snippets}/GetAllDomainsDocTest/http-response.adoc[] ==== Response Structure include::{snippets}/GetAllDomainsDocTest/response-fields.adoc[] === Classification-Categories-Resource This resource provides information which Classification Categories exist in the system. ==== Example Request include::{snippets}/GetAllClassificationCategoriesDocTest/http-request.adoc[] ==== Example Response include::{snippets}/GetAllClassificationCategoriesDocTest/http-response.adoc[] ==== Response Structure include::{snippets}/GetAllClassificationCategoriesDocTest/response-fields.adoc[] === Classification-Types-Resource This resource provides information which Classification Types exist in the system. ==== Example Request include::{snippets}/GetAllClassificationTypesDocTest/http-request.adoc[] ==== Example Response include::{snippets}/GetAllClassificationTypesDocTest/http-response.adoc[] ==== Response Structure include::{snippets}/GetAllClassificationTypesDocTest/response-fields.adoc[] === Current-User-Info-Resource This resource provides information about the current user. include::{snippets}/GetCurrentUserInfoDocTest/http-request.adoc[] ==== Example Response include::{snippets}/GetCurrentUserInfoDocTest/http-response.adoc[] ==== Response Structure include::{snippets}/GetCurrentUserInfoDocTest/response-fields.adoc[] === History-Provider-Is-Enabled This resource returns if history provider is enabled. include::{snippets}/GetHistoryProviderIsEnabled/http-request.adoc[] ==== Example Response include::{snippets}/GetHistoryProviderIsEnabled/http-response.adoc[] ==== Response Structure Returns Boolean which indicates if History Provider is enabled or not. [[resource-subsets]] == Resource-Subsets These subsets of the full resources are used in the Summary-Resources. + Due to a bug with arrays in Spring-Restdocs the snippets used here are not actually generated using the Summary-Resource but by documenting the corresponding subset of an individual Classification Resource. + Further information at [[classification-subset]] === Classification-Subset Subset of the <> include::{snippets}/ClassificationSubset/response-fields.adoc[] [[workbasket-subset]] === Workbasket-Subset Subset of the <> include::{snippets}/WorkbasketSubset/response-fields.adoc[] [[task-subset]] === Task-Subset Subset of the <> include::{snippets}/TaskSubset/response-fields.adoc[] == Embedded Resources Due to a workaround for the same bug as for the <> all fields are prefixed with "_embedded.[].". [[access-item]] === Access Items The access items hold information about the permissions to the workbaskets. include::{snippets}/AccessItemsDocTest/response-fields.adoc[] [[paged-request]] == Example for a paged request (using the AbstractPagingController) Summary Resources can be requested in a paged format. === Example request include::{snippets}/CommonSummaryResourceFields/http-request.adoc[] === Example response include::{snippets}/CommonSummaryResourceFields/response-body.adoc[]