source: VirtualCollectionRegistry/trunk/VirtualCollectionRegistry/Protocol.txt @ 5591

Last change on this file since 5591 was 5591, checked in by Twan Goosen, 10 years ago

Newly created collection are always private. Updated protocol description to reflect this.
  • Property svn:eol-style set to native
  • Property svn:mime-type set to text/plain
File size: 10.7 KB
Line 
1Virtual Collection Registry RESTful web service
2===============================================
3
4The Virtual Collection Registry (VCR) provides a RESTful web service for
5working with the registry.
6
7
81. Prerequisite
9
10    a) Internal XML format for virtual collections:
11       A virtual collection is represented in an internal XML format, which is
12       defined by the W3C XML schema "VirtualCollection.xsd" found in the
13       "src/resources/META-INF" directory.
14       
15    b) The VCR relies on various HTTP headers:
16        - "Content-Type" must be set for POST and PUT requests. Accepted
17          values are "text/xml", "application/xml" or "application/json".
18        - "Accept" can be used all requests. Accepted values are "text/xml",
19          "application/xml" or "application/json". If the header is not set,
20          the VCR assumes "application/xml" as default. An exception is the retrieval
21          of individual collections (2d). This call also accepts "application/x-cmdi+xml"
22          and "text/html" and defaults to the former of these two.
23        - Headers for HTTP Basic Auth need to be set on POST, PUT and DELETE
24          requests.     
25         
26        Note that, as an alternative to the usage of the HTTP "Accept" header, the respons
27        type can be controlled by providing one of the following suffixes to the service
28        URL: ".xml", ".json", ".cmdi", ".html". Not all operations will accept all of
29        these types.
30
31
322. RESTful web service operations
33
34    The following describes the RESTful web service operations. The URIs are
35    relative to a base URI ($BASE), which depends on the machine, where the
36    VCR is installed.
37
38    a) Create a virtual collection (POST)
39                 description: A virtual collection will be created based on the
40                              representation of the virtual collection sent in
41                              the request body. ID and state, if provided, will be
42                              ignored so this will always result in a private collection
43                              with a new identifier.
44                 HTTP method: POST
45                         URI: $BASE/service/virtualcollections
46         URI path parameters: none
47            query parameters: none
48                HTTP headers: Content-Type (required), Accept (optional)
49              authentication: required
50                request body: Depending on Content-Type header either a valid
51                              XML instance or the JSON representation of a
52                              virtual collection conforming to the above
53                              mentioned XML schema. The root element is expected
54                              to be "VirtualCollection"
55                 result body: Depending on Accept header either an XML instance
56                              or the JSON representation of the outcome of the
57                              request. If successful, the result will contain
58                              the ID of the created virtual collection
59
60    b) Update a virtual collection (PUT)
61                 description: The virtual collection identified by the URI will
62                              be updated, actually replaced, with the
63                              representation of the virtual collection sent in
64                              the request body.
65                 HTTP method: PUT
66                         URI: $BASE/service/virtualcollections/$id
67         URI path parameters: $id := (required) is the ID of the virtual
68                                     collection, which is to be changed
69            query parameters: none
70                HTTP headers: Content-Type (required), Accept (optional)
71              authentication: required
72                request body: Depending on Content-Type header either a valid
73                              XML instance or the JSON representation of a
74                              virtual collection conforming to the above
75                              mentioned XML schema. The root element is expected
76                              to be "VirtualCollection"
77                 result body: Depending on Accept header either an XML instance
78                              or the JSON representation of the outcome of the
79                              request.
80
81    c) Delete a virtual collection (DELETE)
82                 description: The virtual collection referenced by the URI will
83                              be deleted.
84                 HTTP method: DELETE
85                         URI: $BASE/service/virtualcollections/$id
86         URI path parameters: $id := (required) is the ID of the virtual
87                                     collection, which is to be deleted 
88            query parameters: none
89                HTTP headers: Accept (optional)
90              authentication: required
91                request body: none
92                 result body: depending on Accept header either an XML instance
93                              or the JSON representation of the outcome of the
94                              request.
95
96    d) Retrieve a virtual collection (GET)
97                 description: The virtual collection referenced by the URI will
98                              be retrieved.
99                 HTTP method: GET
100                         URI: $BASE/service/virtualcollections/$id
101         URI path parameters: $id := (required) is the ID of the virtual
102                                     collection, which is to be retrieved
103            query parameters: none
104                HTTP headers: Accept (optional)
105              authentication: not required
106                request body: none
107                 result body: Depending on Accept header either a CMDI, XML or
108                              JSON representation of the virtual collection, or a redirect
109                              to the collection's detail view in the user interface in
110                              case HTML is requested. If the virtual collection is not
111                              found the appropriate HTTP status code is issued and an
112                              error message is returned.
113                              By default, it returns the CMDI representation for published
114                              collections. If the collection is not published, the
115                              service will respond with another accepted representation.
116                              If only CMDI is represented, it responds with code 406
117                              (Not Acceptable).
118
119    e) Retrieve all / search virtual collections (GET)
120                 description: All virtual collections will be retrieved; if a
121                              query expression is used, only the virtual
122                              collections satisfying the query will be
123                              retrieved.
124                 HTTP method: GET
125                         URI: $BASE/service/virtualcollections
126         URI path parameters: none
127            query parameters: q      := (optional) URL-encoded query
128                                        expression (see below)
129                              offset := (optional) start of result list at
130                                        a given position (default: 0)
131                              count  := (optional) limit the result list to
132                                        a number of entries (default: unlimited)
133                HTTP headers: Accept (optional)
134              authentication: not required
135                request body: none
136                 result body: Depending on Accept header either an XML instance
137                              or the JSON representation of the virtual
138                              collection. If no virtual collection are found
139                              an empty list will be returned.
140
141    f) Retrieve all / search virtual collection owned by the user (GET)
142                 description: All virtual collections owned by the authenticated
143                              user will be retrieved; if a query expression is
144                              used, only the virtual collections satisfying the
145                              query will be retrieved.
146                 HTTP method: GET
147                         URI: $BASE/service/my-virtualcollections
148         URI path parameters: none
149            query parameters: q      := (optional) URL-encoded query
150                                        expression (see below)
151                              offset := (optional) start of result list at
152                                        a given position (default: 0)
153                              count  := (optional) limit the result list to
154                                        a number of entries (default: unlimited)
155                HTTP headers: Accept (optional)
156              authentication: required
157                request body: none
158                 result body: Depending on Accept header either an XML instance
159                              or the JSON representation of the virtual
160                              collection. If no virtual collection are found
161                              an empty list will be returned.
162
163TODO: Add {id}/state
164
165
1663. Virtual Collection Query language (VCRQL)
167     query            = expression
168                      | expression 'and' expression
169                      | expression 'or' expression
170                      | '(' expression ')'
171
172     expression       = 'name'         ( '=' | '<>' ) value
173                      | 'description'  ( '=' | '<>' ) value
174                      | 'creator'      ( '=' | '<>' ) value
175                      | 'email'        ( '=' | '<>' ) value
176                      | 'organization' ( '=' | '<>' ) value
177                      | 'state'        ( '=' | '<>' )
178                                       ( 'public' | 'private' | 'deleted' )
179                      | 'created'      ( '<' | '<=' | '=' | '<>' | '>=' | '>' )
180                                       iso-date
181                      | 'modified'     ( '<' | '<=' | '=' | '<>' | '>=' | '>' )
182                                       iso-date
183
184     value            = double quoted string value, use backslash
185                        for escaping double quotes, use "*" and "?" for
186                        wildcards.
187     iso-date         = full ISO 8601 date: YYYY-MM-DD-T-HH:MM:SSZ
188                        where YYYY := year
189                                MM := month
190                                DD := day
191                                HH := hour
192                                 T := time designator (literal)
193                                MM := minute
194                                SS := second
195                                Z  := UTC indicator (literal)
196
197   (see "src/main/jjtree/eu/clarin/cmdi/virtualcollectionregistry/query/QueryParser.jjt"
198    and "src/main/main/eu/clarin/cmdi/virtualcollectionregistry/query/*.java")
Note: See TracBrowser for help on using the repository browser.