From 7b2d9930a7ce198f6e1186838108072133e86459 Mon Sep 17 00:00:00 2001 From: Luca Frosini Date: Fri, 16 Sep 2022 11:27:06 +0200 Subject: [PATCH] Fixing documentation --- src/main/java/org/gcube/gcat/rest/Item.java | 77 +++++++++++++++++++-- 1 file changed, 73 insertions(+), 4 deletions(-) diff --git a/src/main/java/org/gcube/gcat/rest/Item.java b/src/main/java/org/gcube/gcat/rest/Item.java index 4d3e6d8..2eeb4a1 100644 --- a/src/main/java/org/gcube/gcat/rest/Item.java +++ b/src/main/java/org/gcube/gcat/rest/Item.java @@ -42,6 +42,75 @@ public class Item extends REST implements org.gcube.gcat.api.interf super(ITEMS, ITEM_ID_PARAMETER, CKANPackage.class); } + /** + *

+ * 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. + *

+ * + *

Filtering options

+ *

+ * The listing method offers options to filter the results, thus enacting to search for items including spatial search (see ext_bbox below).
+ * It accepts the following query parameters (a subset of Solr search query parameters, see Solr Query Syntax): + *

+ * + *
+ *
q (string)
+ *
+ * the solr query. Optional. Default: "*:*" See Solr Query Syntax. + * E.g. /items?q=title:foo returns the items with word "foo" in the title; + *
+ * + *
fq (string)
+ *
+ * Filter query. A query string that limits the query results without influencing their scores. + * Note: +site_id:{ckan_site_id} is added to this string prior to the query being executed.
+ * 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)
+ *
+ * additional filter queries to apply.
+ * E.g. /items?q=title:foo&fq_list=... returns the items with word "foo" in the 'title' + *
+ * + *
sort (string)
+ *
+ * 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.
+ * E.g. /items?q=title:foo&sort=name+asc returns the items with word "foo" in the 'title' + * sorting the results by name ascending; + *
+ * + *
include_private (bool)
+ *
+ * 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.
+ * E.g. /items?include_private=true + *
+ * + *
ext_bbox
+ *
+ * The coordinates of the upper-right and bottom-left angle of a rectangular to query for. + * The form is Lat,Long,Lat,Long
+ * E.g. /items?limit=10&offset=0&q=Pollution&ext_bbox=-7.535093,49.208494,3.890688,57.372349 + * returns the first 10 items with 'Pollution' having a spatial coverage in the specified bounding box. + *
+ *
+ * + * @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}
+ */ @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 @@ -49,11 +118,11 @@ public class Item extends REST implements org.gcube.gcat.api.interf */ 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 countOnly) { - if(countOnly) { + @QueryParam(GCatConstants.COUNT_QUERY_PARAMETER) @DefaultValue("false") Boolean count) { + if(count) { CKANPackage ckan = getInstance(); - int count = ckan.count(); - return createCountJson(count); + int size = ckan.count(); + return createCountJson(size); }else { return list(limit, offset); }