= 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.

| `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 <user> has no read permission for <Resource Type> <Resource>.

| `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.
|===

== 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 <<paged-request, paged format>>.

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 +

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 <<task, single task>>.

=== 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 <<task, single task>>.

=== 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 <<create-task-request-structure, request structure>> 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 <<task, single task>>.

=== 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[]

=== 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 <<task, single task>>.

== 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 <<workbasket, single workbasket>>.

==== 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 <<classification, single classification>>.

==== 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 <<classification, single classification>>.

=== 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 <<create-classification-request-structure, request structure>> 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 <<classification, single classification>>.

=== 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 <<classification, classification structure>> 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 <<workbasket, single workbasket>>.

==== 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 <<workbasket, single workbasket>>.

=== Delete workbasket

A `DELETE` request to dalete a workbasket

==== Example Request

include::{snippets}/MarkWorkbasketForDeletionDocTest/http-request.adoc[]

==== Example Response

include::{snippets}/MarkWorkbasketForDeletionDocTest/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 <<create-workbasket-request-structure, request structure>> 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 <<classification, single classification>>.

== 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 <<workbasket, workbasket structure>> 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 <https://github.com/spring-projects/spring-restdocs/issues/473>

[[classification-subset]]
=== Classification-Subset

Subset of the <<classification, Classification Resource>>

include::{snippets}/ClassificationSubset/response-fields.adoc[]

[[workbasket-subset]]
=== Workbasket-Subset

Subset of the <<workbasket, Workbasket Resource>>

include::{snippets}/WorkbasketSubset/response-fields.adoc[]

[[task-subset]]
=== Task-Subset

Subset of the <<task, Task Resource>>

include::{snippets}/TaskSubset/response-fields.adoc[]

== Embedded Resources

Due to a workaround for the same bug as for the <<resource-subsets, Resource-Subsets>> all fields are prefixed with "_embedded.<resource-label>[].".

[[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[]
