Virtual Collection Registry RESTful web service =============================================== The Virtual Collection Registry (VCR) provides a RESTful web service for working with the registry. 1. Prerequisite a) Internal XML format for virtual collections: A virtual collection is represented in an internal XML format, which is defined by the W3C XML schema "VirtualCollection.xsd" found in the "src/resources/META-INF" directory. b) The VCR relies on various HTTP headers: - "Content-Type" must be set for POST and PUT requests. Accepted values are "text/xml", "application/xml" or "application/json". - "Accept" can be used all requests. Accepted values are "text/xml", "application/xml" or "application/json". If the header is not set, the VCR assumes "application/xml" as default. An exception is the retrieval of individual collections (2d). This call also accepts "application/x-cmdi+xml" and "text/html" and defaults to the former of these two. - Headers for HTTP Basic Auth need to be set on POST, PUT and DELETE requests. Note that, as an alternative to the usage of the HTTP "Accept" header, the respons type can be controlled by providing one of the following suffixes to the service URL: ".xml", ".json", ".cmdi", ".html". Not all operations will accept all of these types. 2. RESTful web service operations The following describes the RESTful web service operations. The URIs are relative to a base URI ($BASE), which depends on the machine, where the VCR is installed. a) Create a virtual collection (POST) description: A virtual collection will be created based on the representation of the virtual collection sent in the request body. ID and state, if provided, will be ignored so this will always result in a private collection with a new identifier. HTTP method: POST URI: $BASE/service/virtualcollections URI path parameters: none query parameters: none HTTP headers: Content-Type (required), Accept (optional) authentication: required request body: Depending on Content-Type header either a valid XML instance or the JSON representation of a virtual collection conforming to the above mentioned XML schema. The root element is expected to be "VirtualCollection" result body: Depending on Accept header either an XML instance or the JSON representation of the outcome of the request. If successful, the result will contain the ID of the created virtual collection b) Update a virtual collection (PUT) description: The virtual collection identified by the URI will be updated, actually replaced, with the representation of the virtual collection sent in the request body. HTTP method: PUT URI: $BASE/service/virtualcollections/$id URI path parameters: $id := (required) is the ID of the virtual collection, which is to be changed query parameters: none HTTP headers: Content-Type (required), Accept (optional) authentication: required request body: Depending on Content-Type header either a valid XML instance or the JSON representation of a virtual collection conforming to the above mentioned XML schema. The root element is expected to be "VirtualCollection" result body: Depending on Accept header either an XML instance or the JSON representation of the outcome of the request. c) Delete a virtual collection (DELETE) description: The virtual collection referenced by the URI will be deleted. HTTP method: DELETE URI: $BASE/service/virtualcollections/$id URI path parameters: $id := (required) is the ID of the virtual collection, which is to be deleted query parameters: none HTTP headers: Accept (optional) authentication: required request body: none result body: depending on Accept header either an XML instance or the JSON representation of the outcome of the request. d) Retrieve a virtual collection (GET) description: The virtual collection referenced by the URI will be retrieved. HTTP method: GET URI: $BASE/service/virtualcollections/$id URI path parameters: $id := (required) is the ID of the virtual collection, which is to be retrieved query parameters: none HTTP headers: Accept (optional) authentication: not required request body: none result body: Depending on Accept header either a CMDI, XML or JSON representation of the virtual collection, or a redirect to the collection's detail view in the user interface in case HTML is requested. If the virtual collection is not found the appropriate HTTP status code is issued and an error message is returned. By default, it returns the CMDI representation for published collections. If the collection is not published, the service will respond with another accepted representation. If only CMDI is represented, it responds with code 406 (Not Acceptable). e) Retrieve all / search virtual collections (GET) description: All virtual collections will be retrieved; if a query expression is used, only the virtual collections satisfying the query will be retrieved. HTTP method: GET URI: $BASE/service/virtualcollections URI path parameters: none query parameters: q := (optional) URL-encoded query expression (see below) offset := (optional) start of result list at a given position (default: 0) count := (optional) limit the result list to a number of entries (default: unlimited) HTTP headers: Accept (optional) authentication: not required request body: none result body: Depending on Accept header either an XML instance or the JSON representation of the virtual collection. If no virtual collection are found an empty list will be returned. f) Retrieve all / search virtual collection owned by the user (GET) description: All virtual collections owned by the authenticated user will be retrieved; if a query expression is used, only the virtual collections satisfying the query will be retrieved. HTTP method: GET URI: $BASE/service/my-virtualcollections URI path parameters: none query parameters: q := (optional) URL-encoded query expression (see below) offset := (optional) start of result list at a given position (default: 0) count := (optional) limit the result list to a number of entries (default: unlimited) HTTP headers: Accept (optional) authentication: required request body: none result body: Depending on Accept header either an XML instance or the JSON representation of the virtual collection. If no virtual collection are found an empty list will be returned. TODO: Add {id}/state 3. Virtual Collection Query language (VCRQL) query = expression | expression 'and' expression | expression 'or' expression | '(' expression ')' expression = 'name' ( '=' | '<>' ) value | 'description' ( '=' | '<>' ) value | 'creator' ( '=' | '<>' ) value | 'email' ( '=' | '<>' ) value | 'organization' ( '=' | '<>' ) value | 'state' ( '=' | '<>' ) ( 'public' | 'private' | 'deleted' ) | 'created' ( '<' | '<=' | '=' | '<>' | '>=' | '>' ) iso-date | 'modified' ( '<' | '<=' | '=' | '<>' | '>=' | '>' ) iso-date value = double quoted string value, use backslash for escaping double quotes, use "*" and "?" for wildcards. iso-date = full ISO 8601 date: YYYY-MM-DD-T-HH:MM:SSZ where YYYY := year MM := month DD := day HH := hour T := time designator (literal) MM := minute SS := second Z := UTC indicator (literal) (see "src/main/jjtree/eu/clarin/cmdi/virtualcollectionregistry/query/QueryParser.jjt" and "src/main/main/eu/clarin/cmdi/virtualcollectionregistry/query/*.java")