From d740ead477867ca6066afa920bd702eb1b1f40a6 Mon Sep 17 00:00:00 2001 From: Holger Hagen <19706592+holgerhagen@users.noreply.github.com> Date: Tue, 25 Sep 2018 11:38:48 +0200 Subject: [PATCH] TSK-722: restructured REST doc TOC --- .../src/main/asciidoc/rest-api.adoc | 617 +++++++++--------- 1 file changed, 308 insertions(+), 309 deletions(-) diff --git a/rest/taskana-rest-spring-example/src/main/asciidoc/rest-api.adoc b/rest/taskana-rest-spring-example/src/main/asciidoc/rest-api.adoc index 7ee3bb5c3..0b71a6121 100644 --- a/rest/taskana-rest-spring-example/src/main/asciidoc/rest-api.adoc +++ b/rest/taskana-rest-spring-example/src/main/asciidoc/rest-api.adoc @@ -92,269 +92,6 @@ Summary Resources contain embedded resources and can be requested in a <>. - -==== 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[] - -== 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 <>. - -==== 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 <>. - -=== 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 <> 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 <>. - -=== 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 === 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. + Therefore for the response fields you can refer to the <>. -[[paged-request]] -== Example for a paged request (using the AbstractPagingController) +== Classifications-Resource -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 <>. + +=== 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 <>. + +==== 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[] == Classificationdefinition-Resource @@ -560,6 +409,142 @@ include::../../../{snippets}/ImportClassificationdefinitions/request-fields.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 <>. + +==== 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 <>. + + +=== 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 <>. + == Workbasketdefinition-Resource === Get all workbasket definitions @@ -597,6 +582,45 @@ include::../../../{snippets}/ImportWorkbasketdefinitions/request-fields.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 === Get a task status report @@ -647,45 +671,6 @@ include::../../../{snippets}/GetTaskClassificationReportDocTest/http-response.ad 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) 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 <