source: VirtualCollectionRegistry/tags/VirtualCollectionRegistry-0.4.0-alpha2/VirtualCollectionRegistry/Protocol.txt @ 5557

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

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