* 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}
path parameter to manage such item.
*
* The listing method offers options to filter the results, thus enacting to search for items including spatial search (see ext_bbox below).
*
/items?include_private=true
* Lat,Long,Lat,Long
/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.
* /items?limit=10&offset=0&own_only=true
* * It accepts the following query parameters (a subset of Solr search query parameters, see Solr Query Syntax): *
*/items?q=title:foo
returns the items with word "foo" in the title./items?q=extras_systemtype:MyProfile
returns the items having the profile MyProfile
* /items?q=title:foo&fq=notes:bar
returns with word "foo" in the 'title' and the word "bar" in the 'notes'.
* /items?q=title:foo&fq_list=...
returns the items with word "foo" in the 'title'.
* /items?q=title:foo&sort=name+asc
returns the items with word "foo" in the 'title'
* sorting the results by name ascending.
* approved
after the moderation activation.
*
* It can assume the following values:
* pending
: it returns only the pending items, i.e. the item published by any allowed users and still not Catalogue-Moderator;rejected
: it returns only the rejected items, i.e. the item published by any allowed users and rejected by a Catalogue-Moderator;approved
: it returns only the approved items, i.e. the item published by any allowed users and approved by a Catalogue-Moderator.
* Please note that only Catalogue-Moderators can filter all items by status.
* Other users using this query parameter will get only its own items with such a status in the results.
*
* The result is by default an array list of string containing the ids (i.e. names) of the items. * Anyway, there are two options to get a different results. *
*/items?limit=10&offset=0&count=true
* /items?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.
*
["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}* * In the case the query parameter
all_fields=true
each element of the resulting array contains the item representation:
* E.g.
* * [ * { * "name"="item0", * ..., * "private": false, * "license_url": "http://www.opensource.org/licenses/AFL-3.0" * }, * { * "name"="item1", * ..., * "private": true, * "license_url": "http://www.opensource.org/licenses/AFL-3.0" * }, * ..., * { * "name"="itemN", * ..., * "private": false, * "license_url": "http://www.opensource.org/licenses/AFL-3.0" * } * * ]* * @pathExample /items?limit=10&offset=0 * @responseExample application/json;charset=UTF-8 ["item0","items1",...,"item10"] */ @GET @Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @StatusCodes ({ @ResponseCode ( code = 200, condition = "The request succeeded.") }) /* 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 * @AuthorizationControl(allowedRoles={Role.CATALOGUE_MEMBER, Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class) */ @Override public String list(@QueryParam(GCatConstants.LIMIT_QUERY_PARAMETER) @DefaultValue("10") int limit, @QueryParam(GCatConstants.OFFSET_QUERY_PARAMETER) @DefaultValue("0") int offset) { Boolean countOnly = false; MultivaluedMap
supportedOrganizations
property in
* Read Configuration.
* The defaultOrganization
is used if the author does not specify the organization.
* * In order to make an Item searchable by location, it must have a special extra, with its key named ‘spatial’. * The value must be a valid GeoJSON geometry, for example: *
** { * "type":"Polygon", * "coordinates":[[[2.05827, 49.8625],[2.05827, 55.7447], [-6.41736, 55.7447], [-6.41736, 49.8625], [2.05827, 49.8625]]] * } ** * or * *
* { * "type": "Point", * "coordinates": [-3.145,53.078] * } ** * *
* If at least one profile has been defined within this context, then you need to specify the profile's
* type when creating the item.
* You need to insert, among the extras of the JSON object describing the item, a system:type
* property with one of the available profile, see List Profiles API.
* The validation of the submitted request will be performed against the profile whose type has been specified.
* The profile's properties need to be specified within the extras field as well.
*
* If no profile has been defined, then no validation will be performed.
* Thus you do not need to set any system:type
property.
*
* The user is going to crreate an item can indicate if he/she desires the creation of a social post
* to inform all the users of the VRE that he/she has created the item.
* To request the social post he/she must indicate social_post=true
query parameter.
* The social_post
query parameter is optional and the default value is false
.
* Please note that even the user indicates social_post=true
the social post
* is create only and only if the Catalogue-Manager enabled this feature, see socialPostEnabled
property in
* Read Configuration.
* When the social post is created the a notification to the VRe user is sent if the property
* notificationToUsersEnabled
is true in the above mentioned configuration.
* If false notificationToUsersEnabled=false
the social post will not produce a notification
* to the VRE user which will be only informed about the item pubblication by reading the generated
* social post in the VRE.
*
201 Created
HTTP Status to indicate that the item has been created.
* Some operation could continue in background such as the social post creation.
*
* @pathExample /items?social_post=true
* @requestExample application/json;charset=UTF-8 classpath:/api-docs-examples/item/create-item-request.json
* @responseExample application/json;charset=UTF-8 classpath:/api-docs-examples/item/create-item-response.json
*
*/
@POST
@Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@StatusCodes ({
@ResponseCode ( code = 201, condition = "The item has been created successfully.")
})
@Override
// @AuthorizationControl(allowedRoles={Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class)
public Response create(String json) {
return super.create(json);
}
/**
* @pathExample /items/my_test_item
* @responseExample application/json;charset=UTF-8 classpath:/api-docs-examples/item/read-item-response.json
*/
@GET
@Path("/{" + ITEM_ID_PARAMETER + "}")
@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@StatusCodes ({
@ResponseCode ( code = 200, condition = "The item exists.")
})
@Override
/* 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
* @AuthorizationControl(allowedRoles={Role.CATALOGUE_MEMBER, Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class)
*/
public String read(@PathParam(ITEM_ID_PARAMETER) String id) {
return super.read(id);
}
/**
* Any Catalogue-Admins or above is capable of modifying the authorship of the item.* The bulk delete API provides a way to delete all the items matching certain criteria * (see Filtering Listing options). * The operation returns immediately to the client and continues in background. * There is no way to monitor or stop the running operation. *
* ** When invoked with no arguments, it deletes all the items of the invoking user in the default * CKAN organization for the current context. *
* ** If a Catalogue-Admin or above specifies the query parameter own_only=false * it deletes all the items of all users for the CKAN organization for the current context. * The service ignores the query parameter own_only=false if the requesting user is not * Catalogue-Admin or above. *
* ** Please check the result using the items listing APIs to verify what you will delete. *
* ** The deleted items are moved to the thrash by default. * To completely remove the items (i.e. purge) the user can use the query parameter purge=true. * Please note that the purge action is not reversible. *
* *
* By indicating the query parameter purge=true has the same result of using the bulk
* purge API using the PURGE
HTTP Method.
*
202 Accepted
HTTP Status to indicate that the request has been properly take in charge.
* The operation will continue in background.
* @throws WebServiceException if an error occurs.
*
* @pathExample /items?purge=false
*
*/
@DELETE
@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@StatusCodes ({
@ResponseCode ( code = 202, condition = "The bulk delete/purge has been accepted successfully.")
})
@Override
// @AuthorizationControl(allowedRoles={Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class)
public Response bulkDelete(@QueryParam(GCatConstants.PURGE_QUERY_PARAMETER) @DefaultValue("false") boolean purge) {
deleteAll(purge);
return Response.status(Status.ACCEPTED).build();
}
/**
* * The bulk purge API provides a way to completely remove all the items matching certain criteria * (see Filtering Listing options). Please note that this action is not reversible. * The operation returns immediately to the client and continues in background. * There is no way to monitor or stop the running operation. *
* ** When invoked with no arguments, it purges all the items of the invoking user in the default * CKAN organization for the current context. *
* ** If a Catalogue-Admin or above specifies the query parameter own_only=false, * it purges all the items of all users for the CKAN organization for the current context. * The service ignores the query parameter own_only=false if the requesting user is not * Catalogue-Admin or above. *
* ** Please check the result using the items listing APIs to verify what you will purge. *
* *
* Invoking this API has the same result of using the bulk delete API using the DELETE
HTTP Method
* with the query parameters purge=true.
*
202 Accepted
HTTP Status to indicate that the request has been
* properly taken in charge.The format is the following
* ** { * "system:cm_item_status":"approved", * "message": "..." * } ** *
* The field system:cm_item_status
can have
* the following values: approved
or rejected
, indicating the
* item's new status.
* It is possible to send an optional message together with the new status by adding
* the field message
.
* This operation is available for Catalogue-Moderator only.
*
* Catalogue-Moderator and item author can send just a message to discuss
* the approval of the item by indicating the field message
only.
*
202 Accepted
HTTP Status to indicate that the request has been
* properly taken in charge.