Improving documentation
This commit is contained in:
parent
3455159ecc
commit
a5aee6353e
|
|
@ -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 `<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;
|
||||
* 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
|
||||
==================
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
* Optional, the default is False.<br/>
|
||||
* Only private datasets from the user’s organizations will be returned. For the sysadmins will be returned all private datasets.<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>
|
||||
* </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>
|
||||
* E.g. <code>/items?limit=10&offset=0&own_only=true</code>
|
||||
* </dd>
|
||||
* </dl>
|
||||
*
|
||||
* <h4>Moderated Catalog filtering options</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>
|
||||
* <h4>Filtering options based on Solr query parameters</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.COUNT_QUERY_PARAMETER) @DefaultValue("false") Boolean count) {
|
||||
if(count) {
|
||||
@QueryParam(GCatConstants.OFFSET_QUERY_PARAMETER) @DefaultValue("0") int offset) {
|
||||
|
||||
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)
|
||||
|
|
|
|||
Loading…
Reference in New Issue