package org.gcube.grsf.publisher.rest; import javax.ws.rs.Consumes; import javax.ws.rs.DELETE; import javax.ws.rs.DefaultValue; import javax.ws.rs.GET; import javax.ws.rs.POST; import javax.ws.rs.PUT; 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.Response; import org.gcube.gcat.api.GCatConstants; import org.gcube.grsf.publisher.annotation.PATCH; import org.gcube.grsf.publisher.annotation.PURGE; import org.gcube.grsf.publisher.ckan.record.FisheryRecord; import com.webcohesion.enunciate.metadata.rs.ResourceGroup; import com.webcohesion.enunciate.metadata.rs.ResourceLabel; import com.webcohesion.enunciate.metadata.rs.ResponseCode; import com.webcohesion.enunciate.metadata.rs.StatusCodes; /** * @author Luca Frosini (ISTI - CNR) */ @Path(FisheryRESTAPIs.COLLECTION_PATH) @ResourceGroup("Fishery APIs") @ResourceLabel("Fishery APIs") public class FisheryRESTAPIs extends BaseRESTAPIs { public static final String COLLECTION_PATH = "fishery"; public static final String GRSF_RECORD_UUID_PARAMETER = "FISHERY_GRSF_RECORD_UUID"; public FisheryRESTAPIs() { super(COLLECTION_PATH, GRSF_RECORD_UUID_PARAMETER, FisheryRecord.class); } /** *

* The listing API provides paginated results by using the query parameters limit and offset.
* It returns an array list of string containing the GRSF UUIDs of the fishery records.
* Each name can be used as {fishery_record_id} path parameter to manage such a record. *

* *

Filtering options

*

* The listing method offers options to filter the results, thus enacting to search for records including spatial search (see ext_bbox below).
*

* *

Basic Filtering options

*
*
include_private (bool)
*
* Optional.Default:false.
* If True, private records will be included in the results.
* For the sysadmins will be returned all private datasets.
* E.g. /fishery?include_private=true *
* *
ext_bbox
*
* Optional.Default:null.
* 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. /fishery?limit=10&offset=0&q=Gadus&ext_bbox=-7.535093,49.208494,3.890688,57.372349 * returns the first 10 records with 'Gadus' having a spatial coverage in the specified bounding box. *
* *
* *

Filtering options based on Solr query parameters

*

* It accepts the following query parameters (a subset of Solr search query parameters, see {@see Solr Query Syntax}): *

*
*
q (string)
*
* Optional.Default:"*:*"
* The solr query.
* E.g. /fishery?q=title:Gadus returns the fishery records with word "Gadus" in the title.
* E.g. /fishery?q=extras_systemtype:Fishing Unit returns the GRSF Fishing Unit records. *
* *
fq (string)
*
* Optional.Default:null.
* Filter query. A query string that limits the query results without influencing their scores.
* E.g. /fishery?q=title:Gadus&fq=annotations:test returns with word "Gadus" in the 'title' and the word "test" in the 'Annotations'. *
* *
fq_list (list of strings)
*
* Optional.Default:null.
* Additional filter queries to apply.
* E.g. /fishery?q=title:Gadus&fq_list=... returns the records with word "Gadus" in the 'title'. *
* *
sort (string)
*
* Optional.Default:"relevance asc, metadata_modified desc".
* Sorting of the search results.
* As per the solr documentation, this is a comma-separated string of field names and sort-orderings.
* E.g. /fishery?q=title:Gadus&sort=name+asc returns the records with word "Gadus" in the 'title' * sorting the results by name ascending. *
*
* *

Query results options

*

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

*
*
count (bool)
*
* Optional.Default:false.
* If True, it indicates that the result must contains only the total number of records of the query.
* E.g. /fishery?limit=10&offset=0&count=true *
* *
all_fields (bool)
*
* Optional.Default:false. * If True, the returned array list contains the whole records representation and not only the GRSF UUIDs of the records.
* E.g. /fishery?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 (Default:10) 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 (Default:0) 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.
["GRSF_UUID_0","GRSF_UUID_1",...,"GRSF_UUID_10"]
* * In the case the query parameter count=true it returns the total number of records of the query. * E.g. 
{"count":148}
* * In the case the query parameter all_fields=true each element of the resulting array contains the record representation: * E.g. * 
	 *  [
	 *  	{
	 *  		"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",
	 *  	}
	 *  
	 *  ]
* * @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) @StatusCodes ({ @ResponseCode ( code = 200, condition = "The request succeeded.") }) 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); } /** * This API allows to create a fishery record * @pathExample /fishery * * @requestExample application/json;charset=UTF-8 classpath:/api-docs-examples/fishery/create-fishery-request.json * @responseExample application/json;charset=UTF-8 classpath:/api-docs-examples/fishery/create-fishery-response.json */ @POST @Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @StatusCodes ({ @ResponseCode ( code = 201, condition = "The fishery record has been created successfully.") }) public Response create(String json) { return super.create(json); } /** * This API allows to read a fishery record * @param id the GRSF UUID of the fishery record to read * @pathExample /fishery/d0145931-58d3-4561-bf64-363b61df016b * @responseExample application/json;charset=UTF-8 classpath:/api-docs-examples/fishery/read-fishery-response.json */ @GET @Path("/{" + GRSF_RECORD_UUID_PARAMETER + "}") @Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @StatusCodes ({ @ResponseCode ( code = 200, condition = "The fishery record exists.") }) @Override public String read(@PathParam(GRSF_RECORD_UUID_PARAMETER) String id) { return super.read(id); } /** * This API allows to update a fishery record * @param id the GRSF UUID of the fishery record to update * @pathExample /fishery/d0145931-58d3-4561-bf64-363b61df016b * @requestExample application/json;charset=UTF-8 classpath:/api-docs-examples/fishery/create-fishery-request.json * @responseExample application/json;charset=UTF-8 classpath:/api-docs-examples/fishery/create-fishery-response.json */ @PUT @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 fishery record has been updated successfully.") }) @Override public String update(@PathParam(GRSF_RECORD_UUID_PARAMETER) String id, String json) { return super.update(id, json); } /** * This API allows to patch a fishery record. * The service only updates the provided properties and, * eventually, creates resources (e.g., time series) and * adds tags or groups to the records. * The API does not guarantee that the record is removed from an * old group/tag associated due to the old property value. * @param id the GRSF UUID of the fishery record to patch * @pathExample /fishery/d0145931-58d3-4561-bf64-363b61df016b */ @PATCH @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 fishery record has been patched successfully.") }) @Override public String patch(@PathParam(GRSF_RECORD_UUID_PARAMETER) String id, String json) { return super.patch(id, json); } /** * This API allows to delete/purge (when the purge query parameter is true) * a fishery record. * In case of delete, the fishery record is no longer visible, * but it still exists and can be restored. * In case of purge, the record is completely deleted and cannot be restored. * @param id the GRSF UUID of the fishery record to delete/purge * @pathExample /fishery/d0145931-58d3-4561-bf64-363b61df016b?purge=true */ @DELETE @Path("/{" + GRSF_RECORD_UUID_PARAMETER + "}") @StatusCodes ({ @ResponseCode ( code = 204, condition = "The fishery record has been deleted successfully."), @ResponseCode ( code = 404, condition = "The fishery record was not found.") }) @Override public Response delete(@PathParam(GRSF_RECORD_UUID_PARAMETER) String id, @QueryParam(GCatConstants.PURGE_QUERY_PARAMETER) @DefaultValue("false") Boolean purge) { return super.delete(id, purge); } /** * This API allows to purge a fishery record. * The record cannot be restored. * @param id the GRSF UUID of the fishery record to purge * @pathExample /fishery/d0145931-58d3-4561-bf64-363b61df016b */ @PURGE @Path("/{" + GRSF_RECORD_UUID_PARAMETER + "}") @StatusCodes ({ @ResponseCode ( code = 204, condition = "The fishery record has been purged successfully."), @ResponseCode ( code = 404, condition = "The fishery record was not found.") }) @Override public Response purge(@PathParam(GRSF_RECORD_UUID_PARAMETER) String id) { return super.purge(id); } }