diff --git a/docs/index.rst b/docs/index.rst index cadf564..3058778 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,9 +1,3 @@ -.. Social Service Client documentation master file, created by - sphinx-quickstart on Tue Aug 2 16:11:12 2022. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - - Welcome to gCat documentation! ================================================= @@ -70,8 +64,8 @@ To be RESTful compliant, gCat uses standard HTTP Methods to perform a listing of +--------------+-------------+----------------------------------------+---------------------+--------+------------+ | Operation | HTTP Method | URL | Success HTTP Status | Safe | Idempotent | +==============+=============+========================================+=====================+========+============+ - | Supported | OPTIONS | /{COLLECTION} | 204 No Content ‡ | Y | Y | - | HTTP Methods | | | | | | + | Supported | OPTIONS | /{COLLECTION} | 204 No Content | Y | Y | + | HTTP Methods | | | [#allow]_ | | | +--------------+-------------+----------------------------------------+---------------------+--------+------------+ | List | GET | /{COLLECTION} | 200 OK | Y | Y | +--------------+-------------+----------------------------------------+---------------------+--------+------------+ @@ -81,8 +75,8 @@ To be RESTful compliant, gCat uses standard HTTP Methods to perform a listing of +--------------+-------------+----------------------------------------+---------------------+--------+------------+ | Create | POST | /{COLLECTION} | 201 Created | N | N | +--------------+-------------+----------------------------------------+---------------------+--------+------------+ - | Supported | OPTIONS | /{COLLECTION}/{INSTANCE_ID} | 204 No Content ‡ | Y | Y | - | HTTP Methods | | | | | | + | Supported | OPTIONS | /{COLLECTION}/{INSTANCE_ID} | 204 No Content | Y | Y | + | HTTP Methods | | | [#allow]_ | | | +--------------+-------------+----------------------------------------+---------------------+--------+------------+ | Exist | HEAD | /{COLLECTION}/{INSTANCE_ID} | 204 No Content | Y | Y | +--------------+-------------+----------------------------------------+---------------------+--------+------------+ @@ -92,33 +86,37 @@ To be RESTful compliant, gCat uses standard HTTP Methods to perform a listing of +--------------+-------------+----------------------------------------+---------------------+--------+------------+ | Patch | PATCH | /{COLLECTION}/{INSTANCE_ID} | 200 OK | N | Y | +--------------+-------------+----------------------------------------+---------------------+--------+------------+ - | Delete | DELETE | /{COLLECTION}/{INSTANCE_ID} | 204 No Content | N | N ‡‡ | + | Delete | DELETE | /{COLLECTION}/{INSTANCE_ID} | 204 No Content | N | N [#del]_ | +--------------+-------------+----------------------------------------+---------------------+--------+------------+ - | Purge | DELETE | /{COLLECTION}/{INSTANCE_ID}?purge=true | 204 No Content | N | N ‡‡ | + | Purge | DELETE | /{COLLECTION}/{INSTANCE_ID}?purge=true | 204 No Content | N | N [#del]_ | + +-------------+----------------------------------------+---------------------+--------+------------+ - | | PURGE | /{COLLECTION}/{INSTANCE_ID} | 204 No Content | N | N ‡‡ | + | | PURGE | /{COLLECTION}/{INSTANCE_ID} | 204 No Content | N | N [#del]_ | +--------------+-------------+----------------------------------------+---------------------+--------+------------+ + +.. [#allow] Supported HTTP Methods in **Allow** HTTP Header -‡ Supported HTTP Methods in **Allow** HTTP Header +.. [#del] DELETE has been defined as idempotent. + + *Allamaraju* [#Allamaraju]_ argues that DELETE idempotency should be accomplished client-side. + The server should inform the client if a delete succeeded because the resource was really deleted or it was not found i.e., **404 Not Found** error is suggested instead of **204 No Content**. + The latter situation should be treated as idempotent by the client. + + We share the same vision. For this reason, gCat does not provide server-side idempotency for DELETE and PURGE operations. -‡‡ DELETE has been defined as idempotent. - -*Allamaraju* argues that DELETE idempotency should be accomplished client-side. -The server should inform the client if a delete succeeded because the resource was really deleted or it was not found i.e., *404 Not Found* error is suggested instead of *204 No Content*. -The latter situation should be treated as idempotent by the client. - -We share the same vision. -For this reason, gCat does not provide server-side idempotency for DELETE and PURGE operations. - -:Allamaraju: Allamaraju S. RESTful Web Services Cookbook: Solutions for Improving Scalability and Simplicity . O’Reilly. first ed. 2010 +.. [#Allamaraju] Allamaraju S. RESTful Web Services Cookbook: Solutions for Improving Scalability and Simplicity . O’Reilly. first ed. 2010 -About URL: +About URL +''''''''' -* {COLLECTION} is the plural name of the entity type; -* {INSTANCE_ID} is an identification which enables to univocally identify the instance in the collection. +The presented URL uses the following convention: -About Safety and Idempotency properties: +* **{COLLECTION}** is the plural name of the entity type; +* **{INSTANCE_ID}** is an identification which enables to univocally identify the instance in the collection. + + +About Safety and Idempotency properties +''''''''' * A method is *Safe* if it does not produce any side effects. "This does not prevent an implementation from including behaviour that is potentially harmful, that is not entirely read-only, or that causes side effects while invoking a safe method" @@ -131,12 +129,14 @@ You can find more information about HTTP Methods at ``_, `Squid `_). gCat provide support for this method but to support a wider range of clients it also provides the Purge action via *DELETE* with the additional get parameter ``purge=true`` + Content Type ------------------ @@ -158,25 +158,28 @@ Actually, the service accepts and returns only JSON objects. Except for a `Profile Collection <../api-docs/resource\_Profile.html>`_ which must be manipulated in in XML. + Collections ------------------ -The following collections are available to any users. Non-safe methods can only be invoked by Catalogue Editor +The following collections are available to any users. Non-safe methods can only be invoked by Catalogue-Editor or above. -* Item Collection; +* `Item Collection <../api-docs/resource_Item.html>`_; - * Resource Collection; + * `Resource Collection <../api-docs/resource_Resource.html>`_; -* Profile Collection; -* Namespace Collection; -* License Collection; +* `Profile Collection <../api-docs/resource_Profile.html>`_; +* `Namespace Collection <../api-docs/resource_Namespace.html>`_; +* `License Collection <../api-docs/resource_License.html>`_; -The following collections are available only for Catalogue Admin: +The following collections are available only for Catalogue-Admins or above: -* Group Collection; -* Organization Collection; -* User Collection; -* Configuration Collection. +* `Group Collection <../api-docs/resource_Group.html>`_; +* `Organization Collection <../api-docs/resource_Organization.html>`_; +* `User Collection <../api-docs/resource_User.html>`_; +* `Configuration Collection <../api-docs/resource_Configuration.html>`_. + +An overwiew of the available collections is available at `<../api-docs/index.html>`_; Roles @@ -195,7 +198,7 @@ Another role that is not in the role hierarchy: .. TIP:: - Please note that not all catalogues are moderated. + Please note that not all catalogs are moderated. Java Client ================== diff --git a/src/main/java/org/gcube/gcat/rest/Item.java b/src/main/java/org/gcube/gcat/rest/Item.java index 49a4bf1..9cecb88 100644 --- a/src/main/java/org/gcube/gcat/rest/Item.java +++ b/src/main/java/org/gcube/gcat/rest/Item.java @@ -11,6 +11,7 @@ import javax.ws.rs.Path; import javax.ws.rs.PathParam; import javax.ws.rs.Produces; import javax.ws.rs.QueryParam; +import javax.ws.rs.core.MultivaluedMap; import javax.ws.rs.core.Response; import javax.ws.rs.core.Response.ResponseBuilder; import javax.ws.rs.core.Response.Status; @@ -46,24 +47,25 @@ public class Item extends REST implements org.gcube.gcat.api.interf *

* The listing API provides paginated results by using the query parameters limit and offset.
* It returns an array list of string containing the ids (i.e. names) of the items.
- * Each name can be used as {ITEM_ID_PARAMETER} path parameter to manage such item. + * Each name can be used as {ITEM_ID} path parameter to manage such item. *

* - *

Filtering options

+ *

Filtering options

*

* The listing method offers options to filter the results, thus enacting to search for items including spatial search (see ext_bbox below).
*

+ * + *

Basic Filtering options

*
*
include_private (bool)
*
* Optional.Default:false.
* If True, private datasets will be included in the results.
- * Only private datasets from the user’s organizations will be returned. For the sysadmins will be returned all private datasets. - * Optional, the default is False.
+ * Only private datasets from the user’s organizations will be returned. For the sysadmins will be returned all private datasets.
* E.g. /items?include_private=true *
* - *
ext_bbox
+ *
ext_bbox
*
* Optional.Default:null.
* The coordinates of the upper-right and bottom-left angle of a rectangular to query for. @@ -72,34 +74,15 @@ public class Item extends REST implements org.gcube.gcat.api.interf * returns the first 10 items with 'Pollution' having a spatial coverage in the specified bounding box. *
* - *
own_only (bool)
+ *
own_only (bool)
*
* Optional.Default:false.
* If True, only the items of the requester user will be included in the result.
- * E.g. /items?limit=10&offset=0&own_only=true> - *
- * - *
all_fields
- *
- * Optional.Default:false. - * If True, the returned array list contains the whole item representation and not only the id (i.e. the name). - * E.g. /items?limit=10&offset=0&all_fields=true + * E.g. /items?limit=10&offset=0&own_only=true *
*
* - *

Moderated Catalog filtering options

- *
- *
status (enum)
- *
- * Optional.Default:null.
- * It has sense only for moderated catalogs. - * It can assume the following values: pending; rejected; approved. - * If null return both approved items and items which have been published before the activation of the moderation. - *
- *
- *

- * - *

Solr based Filtering options

+ *

Filtering options based on Solr query parameters

*

* It accepts the following query parameters (a subset of Solr search query parameters, see Solr Query Syntax): *

@@ -112,21 +95,21 @@ public class Item extends REST implements org.gcube.gcat.api.interf * E.g. /items?q=extras_systemtype:MyProfile returns the items having the profile MyProfile * * - *
fq (string)
+ *
fq (string)
*
* Optional.Default:null.
* Filter query. A query string that limits the query results without influencing their scores.
* E.g. /items?q=title:foo&fq=notes:bar returns with word "foo" in the 'title' and the word "bar" in the 'notes'. *
* - *
fq_list (list of strings)
+ *
fq_list (list of strings)
*
* Optional.Default:null.
* Additional filter queries to apply.
* E.g. /items?q=title:foo&fq_list=... returns the items with word "foo" in the 'title'. *
* - *
sort (string)
+ *
sort (string)
*
* Optional.Default:"relevance asc, metadata_modified desc".
* Sorting of the search results.
@@ -136,27 +119,109 @@ public class Item extends REST implements org.gcube.gcat.api.interf *
*
* + *

Moderated Catalog filtering options

+ *
+ *
status (enum)
+ *
+ * Optional.Default:null.
+ * + * It has sense only for moderated catalogs.
+ * When no value is provided, it returns both the items which have been published before the activation of the moderation, + * as weel as the items explicitly approved after the moderation activation. + * + * It can assume the following values: + *
    + *
  • pending: it returns only the pending items, i.e. the item published by any allowed users and still not moderated;
    • + *
  • rejected: it returns only the rejected items, i.e. the item published by any allowed users and rejected by a moderator;
    • + *
  • approved: it returns only the approved items, i.e. the item published by any allowed users and approved by a moderated.
    • + *
+ * + *

+ * Please note that only Catalogue-Moderators can filter items by status.
+ * Other users using this query parameter will get only its own items with such a status in the results. + *

+ *
+ *
+ * + * + *

Query results options

+ *

+ * The result is by default an array list of string containing the ids (i.e. names) of the items. + * Anyway, there are two options to get a different results. + *

+ *
+ *
count (bool)
+ *
+ * Optional.Default:false.
+ * If True, it indicates that the result must contains only the total number of items of the query.
+ * E.g. /items?limit=10&offset=0&count=true + *
+ * + *
all_fields (bool)
+ *
+ * Optional.Default:false. + * If True, the returned array list contains the whole item representation and not only the id (i.e. the name).
+ * E.g. /items?limit=10&offset=0&all_fields=true + *
+ *
+ *

+ * Please note that, count query parameter has priority over all_fields query parameter. + * In other words, all_fields query parameter is not considered is count query parameter is true. + *

+ * * * @param limit 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 count It indicate that the result must contains only the total number of items of the query. * @return It returns an array list of string containing the ids (i.e. names) of the items. * E.g.
["item0","items1",...,"item10"]
* * In the case the query parameter count=true it returns the total number of items of the query. * E.g. 
{"count":148}
+ * + * In the case the query parameter all_fields=true each element of the resulting array contains the item representation: + * E.g. + * 
+	 *  [
+	 *  	{
+	 *  		"name"="item0",
+	 *  		...,
+	 *  		"private": false,
+	 *  		"license_url": "http://www.opensource.org/licenses/AFL-3.0"
+	 *  	},
+	 *  	{
+	 *  		"name"="item1",
+	 *  		...,
+	 *  		"private": true,
+	 *  		"license_url": "http://www.opensource.org/licenses/AFL-3.0"
+	 *  	},
+	 *  	...,
+	 *  	{
+	 *  		"name"="itemN",
+	 *  		...,
+	 *  		"private": false,
+	 *  		"license_url": "http://www.opensource.org/licenses/AFL-3.0"
+	 *  	}
+	 *  
+	 *  ]
*/ @GET @Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) /* Catalogue-Member is not added to VRE members and is assumed as the default role in the catalogue for the VRE members. So we can't enforce * @AuthorizationControl(allowedRoles={Role.CATALOGUE_MEMBER, Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class) */ + @Override public String list(@QueryParam(GCatConstants.LIMIT_QUERY_PARAMETER) @DefaultValue("10") int limit, - @QueryParam(GCatConstants.OFFSET_QUERY_PARAMETER) @DefaultValue("0") int offset, - @QueryParam(GCatConstants.COUNT_QUERY_PARAMETER) @DefaultValue("false") Boolean count) { - if(count) { + @QueryParam(GCatConstants.OFFSET_QUERY_PARAMETER) @DefaultValue("0") int offset) { + + Boolean countOnly = false; + MultivaluedMap queryParameters = uriInfo.getQueryParameters(); + if(queryParameters.containsKey(GCatConstants.COUNT_QUERY_PARAMETER)) { + countOnly = Boolean.parseBoolean(queryParameters.get(GCatConstants.ALL_FIELDS_QUERY_PARAMETER).get(0)); + } + + if(countOnly) { CKANPackage ckan = getInstance(); int size = ckan.count(); return createCountJson(size); @@ -165,14 +230,7 @@ public class Item extends REST implements org.gcube.gcat.api.interf } } - /* - * Not used as REST method, implemented to respect {@link org.gcube.gcat.api.interfaces.Item} interface - */ - @Override - public String list(@QueryParam(GCatConstants.LIMIT_QUERY_PARAMETER) @DefaultValue("10") int limit, - @QueryParam(GCatConstants.OFFSET_QUERY_PARAMETER) @DefaultValue("0") int offset) { - return super.list(limit, offset); - } + @POST @Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)