Fixing documentation

This commit is contained in:
Luca Frosini 2022-09-16 11:27:06 +02:00
parent 599ce4405b
commit 7b2d9930a7
1 changed files with 73 additions and 4 deletions

View File

@ -42,6 +42,75 @@ public class Item extends REST<CKANPackage> implements org.gcube.gcat.api.interf
super(ITEMS, ITEM_ID_PARAMETER, CKANPackage.class); super(ITEMS, ITEM_ID_PARAMETER, CKANPackage.class);
} }
/**
* <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.
* </p>
*
* <h4>Filtering options</h4>
* <p>
* The listing method offers options to filter the results, thus enacting to search for items including spatial search (see ext_bbox below).<br/>
* It accepts the following query parameters (a subset of Solr search query parameters, see Solr Query Syntax):
* </p>
*
* <dl>
* <dt>q (string)</dt>
* <dd>
* the solr query. Optional. Default: "*:*" See Solr Query Syntax.
* E.g. <code>/items?q=title:foo</code> returns the items with word "foo" in the title;
* </dd>
*
* <dt>fq (string)</dt>
* <dd>
* Filter query. A query string that limits the query results without influencing their scores.
* Note: <code>+site_id:{ckan_site_id}</code> is added to this string prior to the query being executed.<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>
* <dd>
* 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>
* <dd>
* sorting of the search results. Optional. Default: 'relevance asc, metadata_modified desc'.
* As per the solr documentation, this is a comma-separated string of field names and sort-orderings.<br/>
* E.g. <code>/items?q=title:foo&sort=name+asc</code> returns the items with word "foo" in the 'title'
* sorting the results by name ascending;
* </dd>
*
* <dt>include_private (bool)</dt>
* <dd>
* if True, private datasets will be included in the results.
* Only private datasets from the users organizations will be returned. For the sysadmins will be returned all private datasets.
* Optional, the default is False.<br/>
* E.g. <code>/items?include_private=true</code>
* </dd>
*
* <dt>ext_bbox</dt>
* <dd>
* The coordinates of the upper-right and bottom-left angle of a rectangular to query for.
* The form is Lat,Long,Lat,Long<br/>
* E.g. <code>/items?limit=10&offset=0&q=Pollution&ext_bbox=-7.535093,49.208494,3.890688,57.372349</code>
* returns the first 10 items with 'Pollution' having a spatial coverage in the specified bounding box.
* </dd>
* </dl>
*
* @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.<br/>
* 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>
*/
@GET @GET
@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @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 /* 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
@ -49,11 +118,11 @@ public class Item extends REST<CKANPackage> implements org.gcube.gcat.api.interf
*/ */
public String list(@QueryParam(GCatConstants.LIMIT_QUERY_PARAMETER) @DefaultValue("10") int limit, 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 countOnly) { @QueryParam(GCatConstants.COUNT_QUERY_PARAMETER) @DefaultValue("false") Boolean count) {
if(countOnly) { if(count) {
CKANPackage ckan = getInstance(); CKANPackage ckan = getInstance();
int count = ckan.count(); int size = ckan.count();
return createCountJson(count); return createCountJson(size);
}else { }else {
return list(limit, offset); return list(limit, offset);
} }