diff --git a/docs/index.rst b/docs/index.rst index 9426bfb..f3996ed 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -29,7 +29,10 @@ You can call the methods of the Web Service by writing your own REST client appl HTTP Statuses ------------------ -Any successful operation returns *200 OK* status code. The create operation returns *201 Created*. Instead, the operations do not provide any content return *204 No Content*. +Any successful operation returns *200 OK* HTTP status code. +The create operation returns *201 Created*. +Instead, the operations do not provide any content return *204 No Content*. +A Background operation returns *202 Accepted*. The most common error status a client can obtain are: diff --git a/src/main/java/org/gcube/gcat/rest/Item.java b/src/main/java/org/gcube/gcat/rest/Item.java index 5f03f0d..50223a3 100644 --- a/src/main/java/org/gcube/gcat/rest/Item.java +++ b/src/main/java/org/gcube/gcat/rest/Item.java @@ -170,10 +170,10 @@ public class Item extends REST implements org.gcube.gcat.api.interf *

* * - * @param limit To get unlimited results the limit query parameters must be set to -1. + * @param limit (Default:10) To get unlimited results the limit query parameters must be set to -1. * If the results are too much the operation could fail. * It is recommended to request no more than 1000 results. - * @param offset The offset parameter indicates the starting position of the result. + * @param offset Default:0) The offset parameter indicates the starting position of the result. * @return It returns an array list of string containing the ids (i.e. names) of the items. * E.g.
["item0","items1",...,"item10"]
* @@ -306,6 +306,40 @@ public class Item extends REST implements org.gcube.gcat.api.interf thread.start(); } + /** + * The bulk delete API provides a way to delete all the times matching certain criteria + * (see Filtering Listing options). + * The operation returns immediately to the client and continues in background. + * There is no way to monitor or stop the running operation. + * + * When invoked with no arguments, it deletes all the items of the invoking user in the default + * CKAN organization for the current context. + * + * If a Catalogue-Admins or above specifies the query parameter own_only=false + * it deletes all the items of all users for the CKAN organization for the current context. + * The service ignores the query parameter own_only=false if the requesting user is not + * Catalogue-Admins or above. + * + *

+ * Please check the result using the items listing APIs to verify what you will delete. + *

+ * + *

+ * The deleted items are moved to the thrash by default. + * To completely remove the items (i.e. purge) the user can use the query parameter purge=true. + * Please note that the purge action is not reversible. + *

+ * + *

+ * By indicating the query parameter purge=true has the same result of using the bulk + * purge API using the PURGE HTTP Method. + *

+ * + * @param purge Default:false) it completely removes all the items in the default CKAN organization. + * @return 202 Accepted HTTP Status to indicate that the request has been properly take in charge. + * The operation will continue in background. + * @throws WebServiceException if an error occurs. + */ @DELETE @Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @Override @@ -315,6 +349,33 @@ public class Item extends REST implements org.gcube.gcat.api.interf return Response.status(Status.ACCEPTED).build(); } + /** + * The bulk purge API provides a way to completely remove all the times matching certain criteria + * (see Filtering Listing options). Please note that this action is not reversible. + * The operation returns immediately to the client and continues in background. + * There is no way to monitor or stop the running operation. + * + * When invoked with no arguments, it purges all the items of the invoking user in the default + * CKAN organization for the current context. + * + * If a Catalogue-Admins or above specifies the query parameter own_only=false, + * it purges all the items of all users for the CKAN organization for the current context. + * The service ignores the query parameter own_only=false if the requesting user is not + * Catalogue-Admins or above. + * + *

+ * Please check the result using the items listing APIs to verify what you will purge. + *

+ * + *

+ * Invoking this API has the same result of using the bulk delete API using the DELETE HTTP Method + * with the query parameters purge=true. + *

+ * + * @return 202 Accepted HTTP Status to indicate that the request has been properly take in charge. + * The operation will continue in background. + * @throws WebServiceException if an error occurs. + */ @PURGE @Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @Override