source: VirtualCollectionRegistry/tags/VirtualCollectionRegistry-0.3.0/Protocol.txt

Last change on this file was 522, checked in by oschonef, 14 years ago
  • re-implement virtual collection query language with javacc
  • add more virtual collection properties to query language (see Protocol.txt)

HEADS UP: changes to query language are not backwards compatible!
  • Property svn:eol-style set to native
  • Property svn:mime-type set to text/plain
File size: 10.4 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.
21        - Headers for HTTP Basic Auth need to be set on POST, PUT and DELETE
22          requests.     
23
24
252. RESTful web service operations
26
27    The following describes the RESTful web service operations. The URIs are
28    relative to a base URI ($BASE), which depends on the machine, where the
29    VCR is installed.
30
31    a) Create a virtual collection (POST)
32                 description: A virtual collection will be created based on the
33                              representation of the virtual collection sent in
34                              the request body.
35                 HTTP method: POST
36                         URI: $BASE/service/virtualcollection
37         URI path parameters: none
38            query parameters: none
39                HTTP headers: Content-Type (required), Accept (optional)
40              authentication: required
41                request body: Depending on Content-Type header either a valid
42                              XML instance or the JSON representation of a
43                              virtual collection conforming to the above
44                              mentioned XML schema. The root element is expected
45                              to be "VirtualCollection"
46                 result body: Depending on Accept header either an XML instance
47                              or the JSON representation of the outcome of the
48                              request. If successful, the result will contain
49                              the ID of the created virtual collection
50
51    b) Update a virtual collection (PUT)
52                 description: The virtual collection identified by the URI will
53                              be updated, actually replaced, with the
54                              representation of the virtual collection sent in
55                              the request body.
56                 HTTP method: PUT
57                         URI: $BASE/service/virtualcollection/$id
58         URI path parameters: $id := (required) is the ID of the virtual
59                                     collection, which is to be changed
60            query parameters: none
61                HTTP headers: Content-Type (required), Accept (optional)
62              authentication: required
63                request body: Depending on Content-Type header either a valid
64                              XML instance or the JSON representation of a
65                              virtual collection conforming to the above
66                              mentioned XML schema. The root element is expected
67                              to be "VirtualCollection"
68                 result body: Depending on Accept header either an XML instance
69                              or the JSON representation of the outcome of the
70                              request.
71
72    c) Delete a virtual collection (DELETE)
73                 description: The virtual collection referenced by the URI will
74                              be deleted.
75                 HTTP method: DELETE
76                         URI: $BASE/service/virtualcollection/$id
77         URI path parameters: $id := (required) is the ID of the virtual
78                                     collection, which is to be deleted 
79            query parameters: none
80                HTTP headers: Accept (optional)
81              authentication: required
82                request body: none
83                 result body: depending on Accept header either an XML instance
84                              or the JSON representation of the outcome of the
85                              request.
86
87    d) Retrieve a virtual collection (GET)
88                 description: The virtual collection referenced by the URI will
89                              be retrieved.
90                 HTTP method: GET
91                         URI: $BASE/service/virtualcollection/$id
92         URI path parameters: $id := (required) is the ID of the virtual
93                                     collection, which is to be retrieved
94            query parameters: none
95                HTTP headers: Accept (optional)
96              authentication: not required
97                request body: none
98                 result body: Depending on Accept header either an XML instance
99                              or the JSON representation of the virtual
100                              collection. If the virtual collection is not found
101                              the appropriate HTTP status code is issued and an
102                              error message is returned.
103
104    e) Retrieve all / search virtual collections (GET)
105                 description: All virtual collections will be retrieved; if a
106                              query expression is used, only the virtual
107                              collections satisfying the query will be
108                              retrieved.
109                 HTTP method: GET
110                         URI: $BASE/service/virtualcollections
111         URI path parameters: none
112            query parameters: q      := (optional) URL-encoded query
113                                        expression (see below)
114                              offset := (optional) start of result list at
115                                        a given position (default: 0)
116                              count  := (optional) limit the result list to
117                                        a number of entries (default: unlimited)
118                HTTP headers: Accept (optional)
119              authentication: not required
120                request body: none
121                 result body: Depending on Accept header either an XML instance
122                              or the JSON representation of the virtual
123                              collection. If no virtual collection are found
124                              an empty list will be returned.
125
126    f) Retrieve all / search virtual collection owned by the user (GET)
127                 description: All virtual collections owned by the authenticated
128                              user will be retrieved; if a query expression is
129                              used, only the virtual collections satisfying the
130                              query will be retrieved.
131                 HTTP method: GET
132                         URI: $BASE/service/my-virtualcollections
133         URI path parameters: none
134            query parameters: q      := (optional) URL-encoded query
135                                        expression (see below)
136                              offset := (optional) start of result list at
137                                        a given position (default: 0)
138                              count  := (optional) limit the result list to
139                                        a number of entries (default: unlimited)
140                HTTP headers: Accept (optional)
141              authentication: required
142                request body: none
143                 result body: Depending on Accept header either an XML instance
144                              or the JSON representation of the virtual
145                              collection. If no virtual collection are found
146                              an empty list will be returned.
147
148    g) Retrieve a virtual collection in CMDI format (GET)
149                 description: The virtual collection referenced by the URI will
150                              be retrieved in CMDI format.
151                 HTTP method: GET
152                         URI: $BASE/service/clarin-virtualcollection/$id
153         URI path parameters: $id := is the ID of the virtual collection,
154                                     which is to be retrieved
155            query parameters: none
156                HTTP headers: none
157              authentication: not required
158                request body: none
159                 result body: The virtual collection in CMDI format If the
160                              virtual collection is not found the appropriate
161                              HTTP status code is issued and an error message
162                              is returned.
163
164
1653. Virtual Collection Query language (VCRQL)
166     query            = expression
167                      | expression 'and' expression
168                      | expression 'or' expression
169                      | '(' expression ')'
170
171     expression       = 'name'         ( '=' | '<>' ) value
172                      | 'description'  ( '=' | '<>' ) value
173                      | 'creator'      ( '=' | '<>' ) value
174                      | 'email'        ( '=' | '<>' ) value
175                      | 'organization' ( '=' | '<>' ) value
176                      | 'state'        ( '=' | '<>' )
177                                       ( 'public' | 'private' | 'deleted' )
178                      | 'created'      ( '<' | '<=' | '=' | '<>' | '>=' | '>' )
179                                       iso-date
180                      | 'modified'     ( '<' | '<=' | '=' | '<>' | '>=' | '>' )
181                                       iso-date
182
183     value            = double quoted string value, use backslash
184                        for escaping double quotes, use "*" and "?" for
185                        wildcards.
186     iso-date         = full ISO 8601 date: YYYY-MM-DD-T-HH:MM:SSZ
187                        where YYYY := year
188                                MM := month
189                                DD := day
190                                HH := hour
191                                 T := time designator (literal)
192                                MM := minute
193                                SS := second
194                                Z  := UTC indicator (literal)
195
196   (see "src/main/jjtree/eu/clarin/cmdi/virtualcollectionregistry/query/QueryParser.jjt"
197    and "src/main/main/eu/clarin/cmdi/virtualcollectionregistry/query/*.java")
Note: See TracBrowser for help on using the repository browser.