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.TraceabilityUnitRecord; import com.webcohesion.enunciate.metadata.Label; 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(TraceabilityUnitRESTAPIs.COLLECTION_PATH) @ResourceGroup("Traceability Unit APIs") @ResourceLabel("Traceability Unit APIs") public class TraceabilityUnitRESTAPIs extends BaseRESTAPIs{ public static final String COLLECTION_PATH = "traceability-unit"; public static final String RECORD_ID_PARAMETER = "traceability_unit_record_id"; public TraceabilityUnitRESTAPIs() { super(COLLECTION_PATH, RECORD_ID_PARAMETER, TraceabilityUnitRecord.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 records.
* Each name can be used as {traceability_unit_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. /traceability-unit?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. /traceability-unit?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. /traceability-unit?q=title:Gadus returns the traceability unit records with word "Gadus" in the title.
* E.g. /traceability-unit?q=extras_systemtype:Traceability Unit returns the GRSF Traceability Unit records. *
* *
fq (string)
*
* Optional.Default:null.
* Filter query. A query string that limits the query results without influencing their scores.
* E.g. /traceability-unit?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. /traceability-unit?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. /traceability-unit?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. /traceability-unit?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. /traceability-unit?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 /traceability-unit?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); } /** * @pathExample /traceability-unit */ @POST @Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @StatusCodes ({ @ResponseCode ( code = 201, condition = "The traceability unit record has been created successfully.") }) public Response create(String json) { return super.create(json); } /** * @pathExample /traceability-unit/004d6fd2-3e49-4246-b321-f768efdaa7b6 */ @GET @Path("/{" + RECORD_ID_PARAMETER + "}") @Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @StatusCodes ({ @ResponseCode ( code = 200, condition = "The traceability unit record exists.") }) @Override public String read(@PathParam(RECORD_ID_PARAMETER) String id) { return super.read(id); } /** * @pathExample /traceability-unit/004d6fd2-3e49-4246-b321-f768efdaa7b6 */ @PUT @Path("/{" + RECORD_ID_PARAMETER + "}") @Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @StatusCodes ({ @ResponseCode ( code = 200, condition = "The traceability unit record has been updated successfully.") }) @Override public String update(@PathParam(RECORD_ID_PARAMETER) String id, String json) { return super.update(id, json); } /** * @pathExample /traceability-unit/004d6fd2-3e49-4246-b321-f768efdaa7b6 */ @PATCH @Path("/{" + RECORD_ID_PARAMETER + "}") @Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @StatusCodes ({ @ResponseCode ( code = 200, condition = "The traceability unit record has been patched successfully.") }) @Override public String patch(@PathParam(RECORD_ID_PARAMETER) String id, String json) { return super.patch(id, json); } /** * @pathExample /traceability-unit/004d6fd2-3e49-4246-b321-f768efdaa7b6 */ @DELETE @Path("/{" + RECORD_ID_PARAMETER + "}") @StatusCodes ({ @ResponseCode ( code = 204, condition = "The traceability unit record has been deleted successfully."), @ResponseCode ( code = 404, condition = "The traceability unit record was not found.") }) @Override public Response delete(@PathParam(RECORD_ID_PARAMETER) String id, @QueryParam(GCatConstants.PURGE_QUERY_PARAMETER) @DefaultValue("false") Boolean purge) { return super.delete(id, purge); } /** * @pathExample /traceability-unit/004d6fd2-3e49-4246-b321-f768efdaa7b6 */ @PURGE @Path("/{" + RECORD_ID_PARAMETER + "}") @StatusCodes ({ @ResponseCode ( code = 204, condition = "The traceability unit record has been purged successfully."), @ResponseCode ( code = 404, condition = "The traceability unit record was not found.") }) @Override public Response purge(@PathParam(RECORD_ID_PARAMETER) String id) { return super.purge(id); } }