nosu
/
taskana
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

TSK-722: restructured REST doc TOC

This commit is contained in:
Holger Hagen 2018-09-25 11:38:48 +02:00
parent f74a70e0d5
commit d740ead477
1 changed files with 308 additions and 309 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

617
rest/taskana-rest-spring-example/src/main/asciidoc/rest-api.adoc
View File

@ -92,269 +92,6 @@ Summary Resources contain embedded resources and can be requested in a <<paged-r
include::../../../{snippets}/CommonSummaryResourceFields/response-fields.adoc[] include::../../../{snippets}/CommonSummaryResourceFields/response-fields.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[]
=== 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[]
== 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 classification. +
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 classification. +
Therefore for the response fields you can refer to the structure of the <<workbasket, single workbasket>>.
=== Mark workbasket for deletion
A `DELETE` request is used to update 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>>.
=== 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[]
== Tasks-Resource == Tasks-Resource
=== Get a list of all tasks === Get a list of all tasks
@ -510,18 +247,130 @@ include::../../../{snippets}/TransferTaskDocTest/http-response.adoc[]
The response-body is essentially the same as for getting a single task. + 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>>. Therefore for the response fields you can refer to the <<task, single task>>.
[[paged-request]] == Classifications-Resource
== Example for a paged request (using the AbstractPagingController)
Summary Resources can be requested in a paged format. This resource provides the entry point with classifications.
=== Example request === Get a list of all classifications
include::../../../{snippets}/CommonSummaryResourceFields/http-request.adoc[] A `GET` request is used to retrieve a classification summary.
=== Example response ==== Example Request
include::../../../{snippets}/CommonSummaryResourceFields/response-body.adoc[] 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>>.
=== 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
=== 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[]
== Classificationdefinition-Resource == Classificationdefinition-Resource
@ -560,6 +409,142 @@ include::../../../{snippets}/ImportClassificationdefinitions/request-fields.adoc
include::../../../{snippets}/ImportClassificationdefinitions/http-response.adoc[] 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 classification. +
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 classification. +
Therefore for the response fields you can refer to the structure of the <<workbasket, single workbasket>>.
=== 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>>.
== Workbasketdefinition-Resource == Workbasketdefinition-Resource
=== Get all workbasket definitions === Get all workbasket definitions
@ -597,6 +582,45 @@ include::../../../{snippets}/ImportWorkbasketdefinitions/request-fields.adoc[]
include::../../../{snippets}/ImportWorkbasketdefinitions/http-response.adoc[] 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 == Monitor-Resource
=== Get a task status report === Get a task status report
@ -647,45 +671,6 @@ include::../../../{snippets}/GetTaskClassificationReportDocTest/http-response.ad
Same as task status report Same as task status report
== 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[]
== Other Resources (using the TaskanaEngineController) == Other Resources (using the TaskanaEngineController)
These resources are directly connected to the Taskana Engine endpoint. These resources are directly connected to the Taskana Engine endpoint.
@ -790,3 +775,17 @@ Due to a workaround for the same bug as for the <<resource-subsets, Resource-Sub
The access items hold information about the permissions to the workbaskets. The access items hold information about the permissions to the workbaskets.
include::../../../{snippets}/AccessItemsDocTest/response-fields.adoc[] 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[]