Improving documentation

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      |
+	| Supported    | OPTIONS     | /{COLLECTION}                          | 204 No Content      |   Y    |     Y      |
-	| HTTP Methods |             |                                        |                     |        |            |
+	| 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      |
+	| Supported    | OPTIONS     | /{COLLECTION}/{INSTANCE_ID}            | 204 No Content      |   Y    |     Y      |
-	| HTTP Methods |             |                                        |                     |        |            |
+	| 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] Allamaraju S. RESTful Web Services Cookbook: Solutions for Improving Scalability and Simplicity . O’Reilly. first ed. 2010
- 
-*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
 
 
-About URL:
+About URL
+'''''''''
 
-* {COLLECTION} is the plural name of the entity type;
+The presented URL uses the following convention:
-* {INSTANCE_ID} is an identification which enables to univocally identify the instance in the collection.
 
-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 `<https://restfulapi.net/htt
 
 
 Uncommon HTTP Methods:
+'''''''''
 
 * PATCH method allows to perform a differential update (i.e. an update which provide only the differences and not the whole new representation);
 * PURGE method is not a standard but is a widely used in service which requires this action
   (e.g. `Varnish <https://varnish-cache.org/docs/3.0/tutorial/purging.html>`_, `Squid <https://wiki.squid-cache.org/SquidFaq/OperatingSquid#How_can_I_purge_an_object_from_my_cache.3F>`_).
   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;
+* `Profile Collection <../api-docs/resource_Profile.html>`_;
-* Namespace Collection;
+* `Namespace Collection <../api-docs/resource_Namespace.html>`_;
-* License Collection;
+* `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;
+* `Group Collection <../api-docs/resource_Group.html>`_;
-* Organization Collection;
+* `Organization Collection <../api-docs/resource_Organization.html>`_;
-* User Collection;
+* `User Collection <../api-docs/resource_User.html>`_;
-* Configuration Collection.
+* `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
 ==================

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<CKANPackage> implements org.gcube.gcat.api.interf
 	 * <p>
 	 * 	The listing API provides paginated results by using the query parameters limit and offset.<br/>
 	 * 	It returns an array list of string containing the ids (i.e. names) of the items.<br/>
-	 * 	Each name can be used as <code>{ITEM_ID_PARAMETER}</code> path parameter to manage such item.
+	 * 	Each name can be used as <code>{ITEM_ID}</code> path parameter to manage such item.
 	 * </p>
 	 * 
-	 * <h4>Filtering options</h4>
+	 * <h3>Filtering options</h3>
 	 * <p>
 	 * 	The listing method offers options to filter the results, thus enacting to search for items including spatial search (see ext_bbox below).<br/>
 	 * </p>
+	 * 
+	 * <h4>Basic Filtering options</h4>
 	 * <dl>
 	 * 	<dt>include_private (bool)</dt>
 	 * 	<dd>
 	 * 		<em>Optional</em>.<em>Default:false</em>.<br/>
 	 * 		If True, private datasets will be included in the results.<br/>
-	 * 		Only private datasets from the user’s organizations will be returned. For the sysadmins will be returned all private datasets. 
+	 * 		Only private datasets from the user’s organizations will be returned. For the sysadmins will be returned all private datasets.<br/>
-	 * 		Optional, the default is False.<br/>
 	 * 		E.g. <code>/items?include_private=true</code>
 	 * 	</dd>
 	 * 	
-	 * 	<dt>ext_bbox</dt>
+	 * 	<dt style="margin-top: 5px;">ext_bbox</dt>
 	 * 	<dd>
 	 * 		<em>Optional</em>.<em>Default:null</em>.<br/>
 	 * 		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<CKANPackage> implements org.gcube.gcat.api.interf
 	 * 		returns the first 10 items with 'Pollution' having a spatial coverage in the specified bounding box.
 	 * 	</dd>
 	 * 
-	 * 	<dt>own_only (bool)</dt>
+	 * 	<dt style="margin-top: 5px;">own_only (bool)</dt>
 	 * 	<dd>
 	 * 		<em>Optional</em>.<em>Default:false</em>.<br/>
 	 * 		If True, only the items of the requester user will be included in the result.<br/>
-	 * 		E.g. <code>/items?limit=10&offset=0&own_only=true>
+	 * 		E.g. <code>/items?limit=10&offset=0&own_only=true</code>
-	 * 	</dd>
-	 * 
-	 * 	<dt>all_fields</dt>
-	 * 	<dd>
-	 * 		<em>Optional</em>.<em>Default:false</em>.
-	 * 		If True, the returned array list contains the whole item representation and not only the id (i.e. the name).
-	 * 		E.g. <code>/items?limit=10&offset=0&all_fields=true</code>
 	 * 	</dd>
 	 * </dl>
 	 * 
-	 * <h4>Moderated Catalog filtering options</h4>
+	 * <h4>Filtering options based on Solr query parameters</h4>
-	 * <dl>
-	 * 	<dt>status (enum)</dt>
-	 * 	<dd>
-	 * 		<em>Optional</em>.<em>Default:null</em>.<br/>
-	 * 		It has sense only for moderated catalogs.
-	 * 		It can assume the following values: <code>pending</code>; <code>rejected</code>; <code>approved</code>.
-	 * 		If null return both approved items and items which have been published before the activation of the moderation.
-	 * 	</dd>
-	 * </dl>
-	 * </p>
-	 * 
-	 * <h4>Solr based Filtering options</h4>
 	 * <p>
 	 * 	It accepts the following query parameters (a subset of Solr search query parameters, see Solr Query Syntax):
 	 * </p>
@@ -112,21 +95,21 @@ public class Item extends REST<CKANPackage> implements org.gcube.gcat.api.interf
 	 *  	E.g. <code>/items?q=extras_systemtype:MyProfile</code> returns the items having the profile <em>MyProfile</em> 
 	 *  </dd>
 	 * 
-	 *  <dt>fq (string)</dt>
+	 *  <dt style="margin-top: 5px;">fq (string)</dt>
 	 *  <dd>
 	 *  	<em>Optional</em>.<em>Default:null</em>.<br/>
 	 *  	Filter query. A query string that limits the query results without influencing their scores.<br/>
 	 *  	E.g. <code>/items?q=title:foo&fq=notes:bar</code> returns with word "foo" in the 'title' and the word "bar" in the 'notes'.
 	 * 	</dd>
 	 * 
-	 * 	<dt>fq_list (list of strings)</dt>
+	 * 	<dt style="margin-top: 5px;">fq_list (list of strings)</dt>
 	 * 	<dd>
 	 * 		<em>Optional</em>.<em>Default:null</em>.<br/>
 	 * 		Additional filter queries to apply.<br/>
 	 * 		E.g. <code>/items?q=title:foo&fq_list=...</code> returns the items with word "foo" in the 'title'.
 	 * 	</dd> 
 	 * 
-	 * 	<dt>sort (string)</dt>
+	 * 	<dt style="margin-top: 5px;">sort (string)</dt>
 	 * 	<dd>
 	 * 		<em>Optional</em>.<em>Default:"relevance asc, metadata_modified desc"</em>.<br/>
 	 * 		Sorting of the search results.<br/> 
@@ -136,27 +119,109 @@ public class Item extends REST<CKANPackage> implements org.gcube.gcat.api.interf
 	 * 	</dd>
 	 * <dl>
 	 * 
+	 * <h4>Moderated Catalog filtering options</h4>
+	 * <dl>
+	 * 	<dt>status (enum)</dt>
+	 * 	<dd>
+	 * 		<em>Optional</em>.<em>Default:null</em>.<br/>
+	 * 		
+	 * 		<span style="font-weight:bold;">It has sense only for moderated catalogs</span>.<br/>
+	 * 		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 <code>approved</code> after the moderation activation.
+	 * 
+	 * 		It can assume the following values:
+	 * 		<ul>
+	 * 			<li><code>pending</code>: it returns only the pending items, i.e. the item published by any allowed users and still not moderated;</li>
+	 * 			<li><code>rejected</code>: it returns only the rejected items, i.e. the item published by any allowed users and rejected by a moderator;</li>
+	 * 			<li><code>approved</code>: it returns only the approved items, i.e. the item published by any allowed users and approved by a moderated.</li>
+	 * 		</ul>
+	 * 
+	 * 		<p>
+	 * 			Please note that only Catalogue-Moderators can filter items by status.<br />
+	 * 			Other users using this query parameter will get only its own items with such a status in the results. 
+	 * 		</p>
+	 * 	</dd>
+	 * </dl>
+	 * 
+	 * 
+	 * <h3>Query results options</h3>
+	 * <p>
+	 * 	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.
+	 * </p>
+	 * <dl>
+	 * 	<dt>count (bool)</dt>
+	 * 	<dd>
+	 * 		<em>Optional</em>.<em>Default:false</em>.<br/>
+	 * 		If True, it indicates that the result must contains only the total number of items of the query.<br/>
+	 * 		E.g. <code>/items?limit=10&offset=0&count=true</code>
+	 * 	</dd>
+	 * 	
+	 * 	<dt style="margin-top: 5px;">all_fields (bool)</dt>
+	 * 	<dd>
+	 * 		<em>Optional</em>.<em>Default:false</em>.
+	 * 		If True, the returned array list contains the whole item representation and not only the id (i.e. the name).</br/>
+	 * 		E.g. <code>/items?limit=10&offset=0&all_fields=true</code>
+	 * 	</dd>
+	 * </dl>
+	 * <p>
+	 * 	Please note that, <code>count</code> query parameter has priority over <code>all_fields</code> query parameter.
+	 * 	In other words,  <code>all_fields</code> query parameter is not considered is <code>count</code> query parameter is true.
+	 * </p> 
+	 * 
 	 * 
 	 * @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.<pre>["item0","items1",...,"item10"]</pre>
 	 * 	
 	 * 	In the case the query parameter <code>count=true</code> it returns the total number of items of the query.
 	 *  E.g. <pre>{"count":148}</pre>
+	 *  
+	 *  In the case the query parameter <code>all_fields=true</code> each element of the resulting array contains the item representation: 
+	 *  E.g.
+	 *  <pre>
+	 *  [
+	 *  	{
+	 *  		"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"
+	 *  	}
+	 *  
+	 *  ]</pre>
 	 */
 	@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.OFFSET_QUERY_PARAMETER) @DefaultValue("0") int offset) {
-			@QueryParam(GCatConstants.COUNT_QUERY_PARAMETER) @DefaultValue("false") Boolean count) {
+		
-		if(count) {
+		Boolean countOnly = false;
+		MultivaluedMap<String,String> 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<CKANPackage> 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)