gCubeSystem
/
grsf-publisher
15
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Adding documentation

This commit is contained in:
Luca Frosini 2024-04-09 17:58:31 +02:00
parent 96f1a5058a
commit a7c6c346ba
1 changed files with 145 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

158
src/main/java/org/gcube/grsf/publisher/rest/FisheryRESTAPIs.java
View File

@ -27,14 +27,146 @@ import com.webcohesion.enunciate.metadata.rs.StatusCodes;
public class FisheryRESTAPIs extends BaseRESTAPIs<Fishery> {
public static final String COLLECTION_PATH = "fishery";
public static final String RECORD_ID_PARAMETER = "fishery_record_id";
public static final String GRSF_RECORD_UUID_PARAMETER = "fishery_record_id";
public FisheryRESTAPIs() {
super(COLLECTION_PATH, RECORD_ID_PARAMETER, Fishery.class);
super(COLLECTION_PATH, GRSF_RECORD_UUID_PARAMETER, Fishery.class);
}
/**
* @pathExample /fishery
* <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 GRSF UUIDs of the records.<br/>
* Each name can be used as <code>{fishery_record_id}</code> path parameter to manage such a record.
* </p>
*
* <h3>Filtering options</h3>
* <p>
* The listing method offers options to filter the results, thus enacting to search for records 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 records will be included in the results.<br/>
* For the sysadmins will be returned all private datasets.<br/>
* E.g. <code>/fishery?include_private=true</code>
* </dd>
*
* <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.
* The form is <code>Lat,Long,Lat,Long</code><br/>
* E.g. <code>/fishery?limit=10&offset=0&q=Gadus&ext_bbox=-7.535093,49.208494,3.890688,57.372349</code>
* returns the first 10 records with 'Gadus' having a spatial coverage in the specified bounding box.
* </dd>
*
* </dl>
*
* <h4>Filtering options based on Solr query parameters</h4>
* <p>
* It accepts the following query parameters (a subset of Solr search query parameters, see {@see <a href="https://solrtutorial.com/solr-query-syntax.html">Solr Query Syntax</a>}):
* </p>
* <dl>
* <dt>q (string)</dt>
* <dd>
* <em>Optional</em>.<em>Default:"*:*"</em><br/>
* The solr query.<br/>
* E.g. <code>/fishery?q=title:Gadus</code> returns the fishery records with word "Gadus" in the title.<br/>
* E.g. <code>/fishery?q=extras_systemtype:Fishing Unit</code> returns the GRSF <em>Fishing Unit</em> records.
* </dd>
*
* <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>/fishery?q=title:Gadus&fq=annotations:test</code> returns with word "Gadus" in the 'title' and the word "test" in the 'Annotations'.
* </dd>
*
* <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>/fishery?q=title:Gadus&fq_list=...</code> returns the records with word "Gadus" in the 'title'.
* </dd>
*
* <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/>
* As per the solr documentation, this is a comma-separated string of field names and sort-orderings.<br/>
* E.g. <code>/fishery?q=title:Gadus&sort=name+asc</code> returns the records with word "Gadus" in the 'title'
* sorting the results by name ascending.
* </dd>
* <dl>
*
* <h3>Query results options</h3>
* <p>
* The result is by default an array list of string containing the GRSF UUIDs of the records.
* 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 records of the query.<br/>
* E.g. <code>/fishery?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 records representation and not only the GRSF UUIDs of the records.</br/>
* E.g. <code>/fishery?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 (<em>Default:10</em>) 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 (<em>Default:0</em>) The offset parameter indicates the starting position of the result.
* @return It returns an array list of string containing the GRSF UUIDs of the records.
* E.g.<pre>["GRSF_UUID_0","GRSF_UUID_1",...,"GRSF_UUID_10"]</pre>
*
* In the case the query parameter <code>count=true</code> it returns the total number of records 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 record representation:
* E.g.
* <pre>
* [
* {
* "name"="GRSF_UUID_0",
* ...,
* "private": false,
* "license_id": "CC-BY-SA-4.0",
* },
* {
* "name"="GRSF_UUID_1",
* ...,
* "private": false,
* "license_id": "CC-BY-SA-4.0",
* },
* ...,
* {
* "name"="GRSF_UUID_N",
* ...,
* "private": false,
* "license_id": "CC-BY-SA-4.0",
* }
*
* ]</pre>
*
* @pathExample /fishery?limit=10&offset=0
* @responseExample application/json;charset=UTF-8 ["GRSF_UUID_0","GRSF_UUID_1",...,"GRSF_UUID_N"]
*/
@GET
@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@ -63,13 +195,13 @@ public class FisheryRESTAPIs extends BaseRESTAPIs<Fishery> {
* @pathExample /fishery/bc26e8d0-6ab3-4547-9922-d40407fc5dbd
*/
@GET
@Path("/{" + RECORD_ID_PARAMETER + "}")
@Path("/{" + GRSF_RECORD_UUID_PARAMETER + "}")
@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@StatusCodes ({
@ResponseCode ( code = 200, condition = "The stock record exists.")
})
@Override
public String read(@PathParam(RECORD_ID_PARAMETER) String id) {
public String read(@PathParam(GRSF_RECORD_UUID_PARAMETER) String id) {
return super.read(id);
}
@ -77,14 +209,14 @@ public class FisheryRESTAPIs extends BaseRESTAPIs<Fishery> {
* @pathExample /fishery/bc26e8d0-6ab3-4547-9922-d40407fc5dbd
*/
@PUT
@Path("/{" + RECORD_ID_PARAMETER + "}")
@Path("/{" + GRSF_RECORD_UUID_PARAMETER + "}")
@Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@StatusCodes ({
@ResponseCode ( code = 200, condition = "The stock record has been updated successfully.")
})
@Override
public String update(@PathParam(RECORD_ID_PARAMETER) String id, String json) {
public String update(@PathParam(GRSF_RECORD_UUID_PARAMETER) String id, String json) {
return super.update(id, json);
}
@ -92,14 +224,14 @@ public class FisheryRESTAPIs extends BaseRESTAPIs<Fishery> {
* @pathExample /fishery/bc26e8d0-6ab3-4547-9922-d40407fc5dbd
*/
@PATCH
@Path("/{" + RECORD_ID_PARAMETER + "}")
@Path("/{" + GRSF_RECORD_UUID_PARAMETER + "}")
@Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@StatusCodes ({
@ResponseCode ( code = 200, condition = "The stock record has been patched successfully.")
})
@Override
public String patch(@PathParam(RECORD_ID_PARAMETER) String id, String json) {
public String patch(@PathParam(GRSF_RECORD_UUID_PARAMETER) String id, String json) {
return super.patch(id, json);
}
@ -107,13 +239,13 @@ public class FisheryRESTAPIs extends BaseRESTAPIs<Fishery> {
* @pathExample /fishery/bc26e8d0-6ab3-4547-9922-d40407fc5dbd
*/
@DELETE
@Path("/{" + RECORD_ID_PARAMETER + "}")
@Path("/{" + GRSF_RECORD_UUID_PARAMETER + "}")
@StatusCodes ({
@ResponseCode ( code = 204, condition = "The stock record has been deleted successfully."),
@ResponseCode ( code = 404, condition = "The stock record was not found.")
})
@Override
public Response delete(@PathParam(RECORD_ID_PARAMETER) String id,
public Response delete(@PathParam(GRSF_RECORD_UUID_PARAMETER) String id,
@QueryParam(GCatConstants.PURGE_QUERY_PARAMETER) @DefaultValue("false") Boolean purge) {
return super.delete(id, purge);
}
@ -122,13 +254,13 @@ public class FisheryRESTAPIs extends BaseRESTAPIs<Fishery> {
* @pathExample /fishery/bc26e8d0-6ab3-4547-9922-d40407fc5dbd
*/
@PURGE
@Path("/{" + RECORD_ID_PARAMETER + "}")
@Path("/{" + GRSF_RECORD_UUID_PARAMETER + "}")
@StatusCodes ({
@ResponseCode ( code = 204, condition = "The stock record has been purged successfully."),
@ResponseCode ( code = 404, condition = "The stock record was not found.")
})
@Override
public Response purge(@PathParam(RECORD_ID_PARAMETER) String id) {
public Response purge(@PathParam(GRSF_RECORD_UUID_PARAMETER) String id) {
return super.purge(id);
}