From a5aee6353ed6a90b4410df65ee23a967a79c44bb Mon Sep 17 00:00:00 2001
From: Luca Frosini
Date: Fri, 16 Sep 2022 16:21:36 +0200
Subject: [PATCH] Improving documentation
---
docs/index.rst | 83 ++++++------
src/main/java/org/gcube/gcat/rest/Item.java | 142 ++++++++++++++------
2 files changed, 143 insertions(+), 82 deletions(-)
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)