/[volute]/trunk/projects/grid/vospace/doc/VOSpace.tex
ViewVC logotype

Contents of /trunk/projects/grid/vospace/doc/VOSpace.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3340 - (show annotations)
Thu Apr 21 23:04:17 2016 UTC (4 years, 3 months ago) by major.brian
File MIME type: application/x-tex
File size: 194512 byte(s)
added server to server vospace examples
1 \documentclass[11pt,a4paper]{ivoa}
2 \input tthdefs
3
4 \usepackage{listings}
5 \usepackage{courier}
6 \usepackage{appendix}
7
8 \lstset{
9 basicstyle=\scriptsize\ttfamily,
10 columns=fullflexible,
11 keepspaces=true,
12 breaklines=true,
13 linewidth=14cm,
14 frame=none
15 }
16
17 \title{VOSpace}
18
19 \ivoagroup{Grid and Web Services Working Group}
20
21 \author{Matthew Graham}
22 \author{Dave Morris}
23 \author{Guy Rixon}
24 \author{Pat Dowler}
25 \author{Andre Schaaff}
26 \author{Doug Tody}
27 \author{Brian Major}
28
29 \editor{Matthew Graham}
30 \editor{Brian Major}
31
32 \previousversion[http://www.ivoa.net/documents/VOSpace/20150601/index.html]{WD-VOSpace-2.1-20150601}
33 \previousversion[http://www.ivoa.net/documents/VOSpace/20140805/index.html]{WD-VOSpace-2.1-20140805}
34 \previousversion[http://www.ivoa.net/documents/VOSpace/20130329/index.html]{REC-VOSpace-2.0-20130329}
35 \previousversion[http://www.ivoa.net/documents/VOSpace/20121221/index.html]{PR-VOSpace-2.0-20121221}
36 \previousversion[http://www.ivoa.net/documents/VOSpace/20120824/index.html]{PR-VOSpace-2.0-20120824}
37 \previousversion[http://www.ivoa.net/documents/VOSpace/20111202/index.html]{PR-VOSpace-2.0-20111202}
38 \previousversion[http://www.ivoa.net/documents/VOSpace/20110628/index.html]{WD-VOSpace-2.0-20110628}
39 \previousversion[http://www.ivoa.net/documents/VOSpace/20101112/index.html]{WD-VOSpace-2.0-20101112}
40 \previousversion[http://www.ivoa.net/documents/VOSpace/20100323/index.html]{WD-VOSpace-2.0-20100323}
41 \previousversion[http://www.ivoa.net/documents/VOSpace/20090513/index.html]{WD-VOSpace-2.0-20090513}
42
43 \begin{document}
44 \begin{abstract}
45 VOSpace is the IVOA interface to distributed storage. This specification presents the second RESTful version of the interface. Except for minor additions to the 2.0 specification, it is functionally equivalent to the SOAP-based VOSpace 1.1 specification. Note that 1.x VOSpace clients will not work with this new version of the interface. VOSpace 2.0 and 2.1 clients will work with 2.1 services. VOSpace 2.1 clients, however, will not work with VOSpace 2.0 services.
46 \end{abstract}
47
48 \section*{Acknowledgments}
49 \label{sec:acknowledgments}
50 This document derives from discussions among the Grid and Web Services working group of the IVOA.
51
52 This document has been developed with support from the National Science Foundation's Information Technology Research Program under Cooperative Agreement AST0122449 with the John Hopkins University, from the UK Science and Technology Facilities Council (STFC), and from the European Commission's Sixth Framework Program via the Optical Infrared Coordination Network (OPTICON).
53
54 \section*{Conformance-related definitions}
55 \label{sec:conformance-related definitions}
56 The words ``MUST'', ``SHALL'', ``SHOULD'', ``MAY'', ``RECOMMENDED'', and
57 ``OPTIONAL'' (in upper or lower case) used in this document are to be
58 interpreted as described in IETF standard, \citep{std:RFC2119}.
59
60 The \emph{Virtual Observatory (VO)} is
61 general term for a collection of federated resources that can be used
62 to conduct astronomical research, education, and outreach.
63 The \href{http://www.ivoa.net}{International
64 Virtual Observatory Alliance (IVOA)} is a global
65 collaboration of separately funded projects to develop standards and
66 infrastructure that enable VO applications.
67
68 \section{Introduction}
69 \label{sec:introduction}
70 VOSpace is the IVOA interface to distributed storage. It specifies how VO agents and applications can use network attached data stores to persist and exchange data in a standard way.
71
72 A VOSpace web service is an access point for a distributed storage network. Through this access point, a client can:
73
74 \begin{itemize}
75 \item add or delete data objects in a tree data structure
76 \item manipulate metadata for the data objects
77 \item obtain URIs through which the content of the data objects can be accessed
78 \end{itemize}
79 VOSpace does not define how the data is stored or transferred, only the control messages to gain access. Thus, the VOSpace interface can readily be added to an existing storage system.
80
81 When we speak of ``a VOSpace'', we mean the arrangement of data accessible through one particular VOSpace service.
82
83 Each data object within a VOSpace service is represented as a node and has a description called a representation. A useful analogy to have in mind when reading this document is that a node is equivalent to a file.
84
85 Nodes in VOSpace have unique identifiers expressed as URIs in the `vos' scheme, as defined below.
86
87 VOSpace 2.0 did not introduce any new functionality to that already offered by prior (SOAP-based) versions of the interface (VOSpace 1.1) but defines a RESTful binding for the interface. VOSpace 2.1 introduces minor changes to VOSpace 2.0 mainly addressing access control and operation optimizations.
88
89 \subsection{Typical use of a VOSpace service}
90 \label{subsec:typical use of a vospace service}
91 A typical use case for VOSpace is uploading a local data file to a remote VOSpace service. This is a two-stage process: creating a description of the data file (representation) in the VOSpace including any metadata (its properties) that they want to associate with it (e.g., MIME type), and defining the transfer operation that will actually see the data file bytes uploaded to the VOSpace service.
92
93 Let's consider the first step: the user provides a XML description of the data file which they HTTP PUT to the appropriate VOSpace URI - this will be the HTTP identifier for the data file in the VOSpace, e.g. http://server.example.com/vospace/nodes/mytable1. The description will resemble this:
94
95 \begin{lstlisting}
96 <vos:node xmlns="http://www.ivoa.net/xml/VOSpace/v2.1"
97 xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
98 uri="vos://example.com!vospace/mytable1"
99 xs:type="vos:UnstructuredDataNode">
100 <vos:properties>
101 <vos:property uri="ivo://ivoa.net/vospace/core#mimetype">
102 text/xml
103 </vos:property>
104 </vos:properties>
105 </vos:node>
106 \end{lstlisting}
107 \noindent
108 Note that the node path is specified in two places on this request, and that they must match:
109 \begin{itemize}
110 \item In the path of the URL in which the client performs the HTTP PUT
111 \item In the node uri attribute of the XML description
112 \end{itemize}
113
114 The service will reply with an amended version of the representation containing service-specific details in addition to the information supplied by the user. These will include data formats that the service can handle for the type of node created in the VOSpace, third-party interfaces (capabilities) to the data that the service offers, and system metadata.
115
116 The user will then describe the data format (the view) they want to use in uploading the file, e.g. VOTable, and the transport protocol (the protocol) that they want to employ to upload the file, e.g. HTTP PUT. This will result in the HTTP POSTing of a XML description of the transfer request to the appropriate VOSpace transfer URL: http://server.example.com/vospace/synctrans. The description will resemble this:
117
118 \begin{lstlisting}
119 <vos:transfer xmlns="http://www.ivoa.net/xml/VOSpace/v2.1">
120 <vos:target>vos://example.com!vospace/mytable1</vos:target>
121 <vos:direction>pushToVoSpace</vos:direction>
122 <vos:view uri="ivo://ivoa.net/vospace/core#votable"/>
123 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpput"/>
124 </vos:transfer>
125 \end{lstlisting}
126
127 The service will reply with a redirect to a location with an amended version of the transfer representation that contains, for the protocols the service supports, URL endpoints that the user may HTTP PUT the data file to, e.g. http://storage1.example.com/vospace/mytable1. The user will then use a regular HTTP client to transfer (PUT) the local file to one of the endpoints. This illustrates an important point about VOSpace - it is only concerned with the server-side management of data storage and transfer. A client negotiates the details of a data transfer with a VOSpace service but the actual transfer of bytes across a network is handled by other tools.
128
129 Similarly, when a user wants to retrieve a data file from a VOSpace service, they will specify the data format (view) they want to use in downloading the file (e.g. VOTable), and the transport protocol (the protocol) that they want to employ to download the file (e.g. HTTP GET), and then HTTP POST a XML description of this transfer request to the VOSpace transfer URL (e.g. http://server.example.com/vospace/synctrans). The description will resemble this:
130
131 \begin{lstlisting}
132 <vos:transfer xmlns="http://www.ivoa.net/xml/VOSpace/v2.1">
133 <vos:target>vos://example.com!vospace/mytable1</vos:target>
134 <vos:direction>pullFromVoSpace</vos:direction>
135 <vos:view uri="ivo://ivoa.net/vospace/core#votable"/>
136 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpget"/>
137 </vos:transfer>
138 \end{lstlisting}
139
140 The service will reply with a redirect to a location that contains an amended version of the transfer representation that contains, for the protocols the service supports, the URL endpoints that the user may HTTP GET the data from, e.g. http://storage1.example.com/vospace/myDataNode. The user can then download the data file by pointing an HTTP client (e.g. web browser) at the specified endpoint.
141
142 \subsection{Role within the VO Architecture}
143 \label{subsec:role within the vo architecture}
144
145 The IVOA Architecture \citep{note:VOARCH} provides a high-level view of how IVOA standards work together to connect users and applications with providers of data and services, as depicted in the diagram in Figure ~\ref{fig:archdiag}.
146
147 \begin{figure}
148 \centering
149
150 % Get the architecture diagram from the TCG chair
151 % http://wiki.ivoa.net/twiki/bin/view/IVOA/IvoaTCG
152 % If they give you a PDF, for now dumb it down to a png by
153 % convert -antialias -density 72x72 archdiag.pdf archdiag.png
154 % Oh -- Notes don't need this; you'd have to remove archdiag.png
155 % from FIGURES in the Makefile, too.
156
157 \includegraphics[width=0.9\textwidth]{archdiag.png}
158 \caption{VOSpace in the IVOA Architecture. This provides an interface to distributed storage. It specifies how applications can use networked data stores to persist and exchange data in a standardized fashion.}
159 \label{fig:archdiag}
160 \end{figure}
161
162 In this architecture, users employ a variety of tools (from the User Layer) to discover and access archives and services of interest (represented in the Resource Layer). VOSpace provides an interface to storage resources containing the results of using these archives and services and also to other storage solutions, e.g., local disks, where users might want to transfer these results for further work. Items in these resources are referenced by a VOSpace identifier which is related to the standard IVOA Resource Identifier (see section 2). This version of VOSpace employs the UWS design pattern \citep{std:UWS} to manage data transfers (see section \ref{subsec:transfers}). VOSpace instances may also employ the IVOA Single-Sign-On standard \citep{std:SSOAUTH} for authentication purposes (see section \ref{sec:access control}) and IVOA Credential Delegation Protocol \citep{std:CDP} to delegate data transfers.
163
164 % Note: add 'search' section to above paragraph when reinstated
165
166 \subsection{Document roadmap}
167 \label{subsec:document roadmap}
168 The rest of this document is structured as follows:
169
170 In Section \ref{sec:vospace identifiers}, we specify the URI syntax for identifying data objects (nodes) in VOSpace.
171
172 In Section \ref{sec:vospace data model}, we present the data model that underpins the VOSpace architecture. This consists of a number of data structures, which have XML representations that are used across the wire in message exchanges with a VOSpace service. These structures represent:
173
174 \begin{itemize}
175 \item the data objects themselves (nodes)
176 \item metadata that can be associated with a data object (properties)
177 \item third-party interfaces to the data (capabilities)
178 \item the data format used when transferring data objects across the wire (views)
179 \item the transport protocol employed in a data transfer (protocols)
180 \item the data transfer itself (transfers)
181 % \item searches of data objects (searches)
182 \end{itemize}
183
184 We also describe the REST bindings between these representations and their URIs (HTTP identifiers).
185
186 In Section \ref{sec:access control}, we outline how security and access control policies are currently handled in VOSpace.
187
188 In Section \ref{sec:web service operations}, we detail the operations that the VOSpace interface supports. These handle access to service-level metadata, the creation and manipulation of nodes within the VOSpace, access to node metadata (properties) and data transfer to and from the VOSpace.
189
190 In Appendex \ref{sec:machine readable definitions}, we formally define the VOSpace interface with a machine readable description of its requests and responses and in Appendix \ref{sec:compliance matrix}, we present a compliance matrix listing the mandatory behaviour required of a valid VOSpace 2.1 service.
191
192 \section{VOSpace identifiers}
193 \label{sec:vospace identifiers}
194 The identifier for a node in VOSpace SHALL be a URI with the scheme vos.
195
196 Such a URI SHALL have the following parts with the meanings and encoding rules defined in RFC3986 \citep{std:RFC3986}.
197
198 \begin{itemize}
199 \item scheme
200 \item naming authority
201 \item path
202 \item (optional) query
203 \item (optional) fragment identifier (with the expected semantics noted in URI fragments in IVOA specifications \citep{note:uriforms})
204 \end{itemize}
205
206 The naming authority for a VOSpace node SHALL be the VOSpace service through which the node was created. The authority part of the URI SHALL be constructed from the IVO registry identifier \citep{std:VOID} for that service by deleting the ivo:// prefix and changing all forward-slash characters(`/') in the resource key to exclamation marks (`!') or tildes (`$\mathtt{\sim}$'). Note that a service SHALL be consistent in its use of separator characters (`!' or `$\mathtt{\sim}$') when referring to its own data but SHALL accept either as valid in URIs in service requests. For the rest of the document, we shall use `!' as the default character.
207
208 This is an example of a possible VOSpace identifier.
209
210 \begin{verbatim}
211 vos://example.com!vospace/myresults/siap-out-1.vot
212 \end{verbatim}
213
214 The URI scheme is \emph{vos}
215
216 Using a separate URI scheme for VOSpace identifiers enables clients to distinguish between IVO registry identifiers and VOSpace identifiers.
217
218 \emph{example.com!vospace} is the authority part of the URI, corresponding to the IVO registry identifier \emph{ivo://example.com/vospace}. This is the IVO registry identifier of the VOSpace service that contains the node.
219
220 \emph{/siap-out-1.vot} is the URI path
221
222 Slashes in the URI path imply a hierarchical arrangement of data: the data object identified by \emph{vos://example.com!vospace/myresults/siap-out-1.vot} is within the container identified by \emph{vos://example.com!vospace/myresults}.
223
224 Literal space characters are also not allowed in URIs.
225
226 All ancestors in the hierarchy SHALL be resolvable as containers (ContainerNodes), all the way up to the root node of the space (this precludes any system of implied hierarchy in the naming scheme for nodes with ancestors that are just logical entities and cannot be reified, e.g. the Amazon S3 system).
227
228 A VOSpace identifier is globally unique, and identifies one specific node in a specific VOSpace service.
229
230 The standardID for this specification SHALL be:
231 \begin{verbatim}
232 ivo://ivoa.net/std/VOSpace/v2.1
233 \end{verbatim}
234
235 \subsection{Identifier resolution}
236 \label{subsec:identifier resolution}
237 A VOSpace identifier can be resolved to a HTTP endpoint for accessing representations of the node associated with it. A client SHOULD use the following procedure to resolve access to a VOSpace node from a VOSpace identifier:
238
239 \begin{itemize}
240 \item Resolve HTTP service endpoint of VOSpace service with registry
241 \item Append ``nodes/'' and the path following the naming authority part of the VOSpace identifier to the service endpoint
242 \end{itemize}
243
244 \noindent
245 Given the example identifier
246
247 \begin{verbatim}
248 vos://example.com!vospace/container-6/siap-out-1.vot?foo=bar
249 \end{verbatim}
250
251 \noindent
252 Processing the URI to resolve the VOSpace service would involve:
253 \\* \\*
254 1. Extract the IVO registry identifier of the VOSpace service by prepending an ivo scheme to the naming authority part:
255 \begin{verbatim}
256 ivo://example.com/vospace
257 \end{verbatim}
258 2. Resolve the IVO identifier in a registry and retrieve the access URL of the service endpoint:
259 \begin{verbatim}
260 http://server.example.com/vospace
261 \end{verbatim}
262 3. Append ``nodes/'' and the path part of the VOSpace identifier:
263 \begin{verbatim}
264 http://server.example.com/vospace/nodes/container-6/siap-out-1.vot?foo=bar
265 \end{verbatim}
266
267 Note that any fragment identifier in the identifier SHOULD be removed when resolving the identifier to a HTTP endpoint, consistent with the implied semantics of URI fragments \citep{note:uriforms}.
268
269 \section{VOSpace data model}
270 \label{sec:vospace data model}
271
272 \subsection{Nodes and node types}
273 \label{subsec:nodes and node types}
274
275 We refer to the arrangement of data accessible through one particular VOSpace service as ``a VOSpace''.
276
277 Each data object within a VOSpace SHALL be represented as a node that is identified by a URI.
278
279 There are different types of nodes and the type of a VOSpace node determines how the VOSpace service stores and interprets the node data.
280
281 The types are arranged in a hierarchy (see Figure ~\ref{fig:nodehierarchy}), with more detailed types inheriting the structure of more generic types.
282
283 \begin{figure}
284 \centering
285 \includegraphics[width=0.9\textwidth]{vospace-node-hierarchy.png}
286 \caption{Node hierarchy - This shows the inheritance structure for the different types of nodes in VOSpace.}
287 \label{fig:nodehierarchy}
288 \end{figure}
289
290 The following types (and representations) are defined:
291
292 \begin{itemize}
293 \item Node is the most basic type
294 \item ContainerNode describes a data item that can contain other data items
295 \item DataNode describes a data item stored in the VOSpace
296 \item UnstructuredDataNode describes a data item for which the VOSpace does not understand the data format
297 \item StructuredDataNode describes a data item for which the space understands the format and may make transformations that preserve the meaning of the data.
298 \item LinkNode describes a node that points to another node.
299 \end{itemize}
300
301 When data is stored and retrieved from an \emph{UnstructuredDataNode}, the bit pattern read back SHALL be identical to that written.
302
303 When data is stored and retrieved from a \emph{StructuredDataNode}, the bit pattern returned MAY be different to the original. For example, storing tabular data from a VOTable file will preserve the tabular data, but any comments in the original XML file may be lost.
304
305 A Node representation SHALL have the following elements:
306
307 \begin{itemize}
308 \item \emph{uri}: the vos:// identifier for the node, URI-encoded according to RFC3986 \citep{std:RFC3986}.
309 \item \emph{properties}: a set of metadata properties for the node
310 \item \emph{capabilities}: a third-party interface to a data object
311 \end{itemize}
312
313 In addition, a \emph{DataNode} representation SHALL have the following elements:
314
315 \begin{itemize}
316 \item \emph{accepts}: a list of the views (data formats) that the node can accept
317 \item \emph{provides}: a list of the views (data formats) that the node can provide
318 \end{itemize}
319
320 A \emph{DataNode} representation MAY have the following element:
321
322 \begin{itemize}
323 \item \emph{busy}: a boolean flag to indicate that the data associated with the node cannot be accessed.
324 \end{itemize}
325
326 The \emph{busy} flag is used to indicate that an internal operation is in progress, and the node data is not available.
327
328 A \emph{ContainerNode} representation SHALL have the following elements, in addition to those it inherits from the \emph{Node} representation:
329
330 \begin{itemize}
331 \item \emph{nodes}: a list of the direct children, if applicable, that the container has. Each child is represented as a node subelement containing its vos:// identifier, URI-encoded according to RFC3986 \citep{std:RFC3986}
332 \end{itemize}
333
334 A \emph{LinkNode} representation SHALL have the following elements, in addition to those it inherits from the Node representation:
335
336 \begin{itemize}
337 \item \emph{target}: the target URI, URI-encoded according to RFC3986 \citep{std:RFC3986}
338 \end{itemize}
339
340 The link target can be a URI that points to any type of resource, including other VOSpace Nodes (within the same VOSpace service or in another service), or external resources outside VOSpace altogether.
341
342 The properties of a \emph{LinkNode} do not propagate to the target of the \emph{LinkNode}, i.e., a property attached to a LinkNode does not also get attached to the target node. One use case is to enable third-party annotations to be associated with a resource but without the resource itself getting cluttered with unnecessary metadata. In this case, the client creates a \emph{LinkNode} pointing to the resource in question and then adds the annotations as properties of the \emph{LinkNode}.
343
344 Both the \emph{ContainerNode} and the \emph{LinkNode} SHALL have no data bytes associated with them.
345
346 The set of node types defined by this standard is closed; new types may be introduced only via new versions of the standard.
347
348 To comply with the standard, a client or service SHALL be able to parse XML representations of all the node types defined in the current specification.
349
350 Note: This does not require all services to support all of the Node types, just that it can process an XML request containing any of the types. If the service receives a request for a type that it does not support, the service SHOULD return a \emph{TypeNotSupported} fault. The service SHALL NOT throw an XML parser error if it receives a request for a type that it does not support.
351
352 \subsection{Properties}
353 \label{subsec:properties}
354 \emph{Properties} are simple string-based metadata properties associated with a node.
355
356 Individual \emph{Properties} should contain simple short string values, not large blocks of information. If a system needs to attach a large amount of metadata to a node, then it should either use multiple small \emph{Properties}, or a single \emph{Property} containing a URI or URL pointing to an external resource that contains the additional metadata.
357
358 A \emph{Property} representation SHALL have the following elements:
359
360 \begin{itemize}
361 \item \emph{uri}: the Property identifier
362 \item \emph{value}: the string value of the Property
363 \item \emph{readOnly}: a boolean flag to indicate that the Property cannot be changed by the client
364 \end{itemize}
365
366 Properties may be set by the client or the service.
367
368 \subsubsection{Property values}
369 \label{subsubsec:property values}
370 Unless they have special meaning to the service or client, Properties are treated as simple string values.
371
372 When a \emph{Property} can take multiple values, e.g., a list of groups which can access a particular resource, these SHOULD be comma-separated, unless the property description defines a specific delimiter.
373
374 Some \emph{Properties} may have meaning to the service; others may have meaning only to one specific type of client. A service implementation does not need to understand the meaning of all the \emph{Properties} of a node. Any Properties that it does not understand can simply be stored as text strings.
375
376 \subsubsection{Property identifiers}
377 \label{subsubsec:property identifiers}
378 Every new type of \emph{Property} SHALL require a unique URI to identify the \emph{Property} and its meaning.
379
380 The rules for the \emph{Property} identifiers are similar to the rules for namespace URIs in XML schema. The only restriction is that it SHALL be a valid (unique) URI.
381
382 \begin{itemize}
383 \item An XML schema namespace identifier can be just a simple URN, e.g. urn:my-namespace
384 \item Within the IVOA, the convention for namespace identifiers is to use a HTTP URL pointing to the namespace schema or a resource describing it
385 \end{itemize}
386
387 The current VOSpace schema defines \emph{Property} identifiers as anyURI. The only restriction is that it SHALL be a valid (unique) URI.
388
389 \begin{itemize}
390 \item A \emph{Property} URI can be a simple URN, e.g. urn:my-property
391 \end{itemize}
392
393 This may be sufficient for testing and development on a private system, but it is not scalable for use on a public service.
394
395 For a production system, any new Properties SHOULD have unique URIs that can be resolved into to a description of the Property.
396
397 Ideally, these should be IVO registry URIs that point to a description registered in the IVO registry:
398
399 \begin{itemize}
400 \item ivo://my-registry/vospace/properties\#my-property
401 \end{itemize}
402
403 Using an IVO registry URI to identify Properties has two main advantages:
404
405 \begin{itemize}
406 \item IVO registry URIs are by their nature unique, which makes it easy to ensure that different teams do not accidentally use the same URI
407 \item If the IVO registry URI points to a description registered in the IVO registry, this provides a mechanism to discover what the Property means
408 \end{itemize}
409
410 \subsubsection{Property descriptions}
411 \label{subsubsec:property descriptions}
412 If the URI for a particular Property is resolvable, i.e. an IVO registry identifier or a HTTP URL, then it SHOULD point to an XML resource that describes the Property.
413
414 A Property description SHOULD describe the data type and meaning of a Property.
415
416 A PropertyDescription SHOULD have the following members:
417
418 \begin{itemize}
419 \item \emph{uri}: the formal URI of the Property
420 \item \emph{DisplayName}: A display name for the Property
421 \item \emph{Description}: A text block describing the meaning and validation rules of the Property
422 \end{itemize}
423
424 A PropertyDescription MAY have the following OPTIONAL members:
425
426 \begin{itemize}
427 \item \emph{UCD}: the Universal Content Descriptor (in the UCD1 + scheme) for the Property
428 \item \emph{Unit}: the unit of measurement of the Property
429 \end{itemize}
430
431 The information in a Property description can be used to generate a UI for displaying and modifying the different types of Properties.
432
433 Note that at the time of writing, the schema for registering PropertyDescriptions in the IVO registry has not been finalized.
434
435 \paragraph{UI Display name}
436 If a client is unable to resolve a Property identifier into a description, then it may just display the identifier as a text string:
437
438 \begin{itemize}
439 \item urn:modifieddate
440 \end{itemize}
441
442 If the client can resolve the Property identifier into a description, then the client may use the information in the description to display a human readable name and description of the Property:
443
444 \begin{itemize}
445 \item Last modification date of the node data
446 \end{itemize}
447
448 \paragraph{Property editors}
449 If the client is unable to resolve a Property identifier into a description, or does not understand the type information defined in the description, then the client MAY treat the Property value as a simple text string.
450
451 If the client can resolve the Property identifier into a description, then the client MAY use the information in the description to display an appropriate editing tool for the Property.
452
453 In the current version of the specification the rules for editing Properties are as follows:
454
455 \begin{itemize}
456 \item A service MAY impose validation rules on the values of specific types of Properties
457 \item If a client attempts to set a Property to an invalid value, then the service MAY reject the change
458 \item Where possible, the validation rules for a type of Property SHOULD be defined in the Property description
459 \end{itemize}
460
461 Future versions of the VOSpace specification may extend the PropertyDescription to include more specific machine readable validation rules for a Property type.
462
463 Note that at the time of writing, the schema for registering validation rules in PropertyDescriptions has not been finalized.
464
465 \subsubsection{Standard properties}
466 \label{subsubsec:standard properties}
467 Property URIs and PropertyDescriptions for the core set of Properties are registered under a StandardKeyEnumeration resource \citep{std:STDREGEXT} in the IVOA registry with the resource identifier ivo://ivoa.net/vospace/core. The following URIs SHOULD be used to represent the service properties:
468
469 \begin{itemize}
470 \item ivo://ivoa.net/vospace/core\#title SHALL be used as the property URI denoting a name given to the resource
471 \item ivo://ivoa.net/vospace/core\#creator SHALL be used as the property URI denoting an entity primarily responsible for making the resource
472 \item ivo://ivoa.net/vospace/core\#subject SHALL be used as the property URI denoting the topic of the resource
473 \item ivo://ivoa.net/vospace/core\#description SHALL be used as the property URI denoting an account of the resource
474 \item ivo://ivoa.net/vospace/core\#publisher SHALL be used as the property URI denoting an entity responsible for making the resource available
475 \item ivo://ivoa.net/vospace/core\#contributor SHALL be used as the property URI denoting an entity responsible for making contributions to this resource
476 \item ivo://ivoa.net/vospace/core\#date SHALL be used as the property URI denoting a point or period of time associated with an event in the lifecycle of the resource
477 \item ivo://ivoa.net/vospace/core\#type SHALL be used as the property URI denoting the nature or genre of the resource
478 \item ivo://ivoa.net/vospace/core\#format SHALL be used as the property URI denoting the file format, physical medium, or dimensions of the resource
479 \item ivo://ivoa.net/vospace/core\#identifier SHALL be used as the property URI denoting an unambiguous reference to the resource within a given context
480 \item ivo://ivoa.net/vospace/core\#source SHALL be used as the property URI denoting a related resource from which the described resource is derived
481 \item ivo://ivoa.net/vospace/core\#language SHALL be used as the property URI denoting a language of the resource
482 \item ivo://ivoa.net/vospace/core\#relation SHALL be used as the property URI denoting a related resource
483 \item ivo://ivoa.net/vospace/core\#coverage SHALL be used as the property URI denoting the spatial or temporal topic of the resource, the spatial applicability of the resource, or the jurisdiction under which the resource is relevant
484 \item ivo://ivoa.net/vospace/core\#rights SHALL be used as the property URI denoting information about rights held in and over the resource
485 \item ivo://ivoa.net/vospace/core\#availableSpace SHALL be used as the property URI denoting the amount of space available within a container
486 \item ivo://ivoa.net/vospace/core\#groupread SHALL be used as the property URI denoting the list of groups which can only read this resource (read-only)
487 \item ivo://ivoa.net/vospace/core\#groupwrite SHALL be used as the property URI denoting the list of groups which can read and write to this resource (read-write)
488 \item ivo://ivoa.net/vospace/core\#publicread SHALL be used as the property URI denoting whether this resource is world readable (anon-read-only)
489 \item ivo://ivoa.net/vospace/core\#quota SHALL be used as the property URI denoting the value of a system quota on the resource
490 \item ivo://ivoa.net/vospace/core\#length SHALL be used as the property URI denoting the length or size of a resource
491 \item ivo://ivoa.net/vospace/core\#mtime SHALL be used as the property URI denoting the data modification time
492 \item ivo://ivoa.net/vospace/core\#ctime SHALL be used as the property URI denoting status change (aka metadata modification) time
493 \item ivo://ivoa.net/vospace/core\#btime SHALL be used as the property URI denoting initial creation time
494 \end{itemize}
495
496 However, this is not intended to be a closed list, different implementations are free to define and use their own Properties.
497
498 \subsection{Capabilities}
499 \label{subsec:capabilities}
500 A Capability describes a third-party interface to a node. One application of this would be to enable data access to a node or its contents using a 3rd party service interface.
501
502 A Capability representation SHALL have the following members:
503
504 \begin{itemize}
505 \item \emph{uri}: the Capability identifier
506 \item \emph{endpoint}: the endpoint URL to use for the third-party interface
507 \item \emph{param}: a set of parameters for the capability
508 \end{itemize}
509
510 \subsubsection{Example capability use cases}
511 \label{subsubsec:example capability use cases}
512 A ContainerNode containing image files may offer a DAL SIAP capability so that the images in the container can be accessed using a SIAP service. In this way, a user could create a (DAL enabled) Container in VOSpace, transfer some images into it and then query the set of images using the SIAP interface.
513
514 Another example is a DataNode that provides a OpenStack Swift capability so that the OpenStack service API is exposed on that node.
515
516 \subsubsection{Capability identifiers}
517 \label{subsubsec:capability identifiers}
518 Every new type of Capability SHALL require a unique URI to identify the Capability. The rules for the Capability identifiers are similar to the rules for namespace URIs in XML schema. The only restriction is that it SHALL be a valid (unique) URI.
519
520 \begin{itemize}
521 \item An XML schema namespace identifier can be just a simple URN, e.g. urn:my-namespace
522 \item Within the IVOA, the convention for namespace identifiers is to use a HTTP URL pointing to the namespace schema, or a resource describing it.
523 \end{itemize}
524
525 The VOSpace schema defines Capability identifiers as anyURI. The only restriction is that it SHALL be a valid (unique) URI.
526
527 \begin{itemize}
528 \item A Capability URI can be a simple URN, e.g. urn:my-capability
529 \end{itemize}
530
531 This may be sufficient for testing and development on a private system, but it is not suitable for use on a public service. For a production system, any new Capabilities SHOULD have unique URIs that can be resolved into a description of the Capability. Ideally, these SHOULD be IVO registry URIs that point to a description registered in the IVO registry:
532
533 \begin{itemize}
534 \item ivo://my-registry/vospace/capabilities\#my-capability
535 \end{itemize}
536
537 Using an IVO registry URI to identify Capabilities has two main advantages:
538
539 \begin{itemize}
540 \item IVO registry URIs are by their nature unique, which makes it easy to ensure that different teams do not accidentally use the same URI
541 \item If the IVO registry URI points to a description registered in the IVO registry, this provides a mechanism to discover how to use the Capability.
542 \end{itemize}
543
544 \subsubsection{Capability descriptions}
545 \label{subsubsec:capability descriptions}
546 If the URI for a particular Capability is resolvable, i.e. an IVO registry identifier or a HTTP URL then it SHOULD point to an XML resource that describes the Capability.
547
548 A CapabilityDescription SHOULD describe the third-party interface and how it should be used in this context. A CapabilityDescription SHOULD have the following members:
549
550 \begin{itemize}
551 \item \emph{uri}: the formal URI of the Capability
552 \item \emph{DisplayName}: a simple display name of the Capability.
553 \item \emph{Description}: a text block describing the third-party interface and how it should be used in this context.
554 \end{itemize}
555
556 Note that at the time of writing, the schema for registering CapabilityDescriptions in the IVO registry has not been finalized.
557
558 \subsubsection{UI display name}
559 \label{subsubsection:ui display ame}
560 If a client is unable to resolve a Capability identifier into a description then it may just display the identifier as a text string:
561
562 \begin{itemize}
563 \item Access data using urn:openstack
564 \end{itemize}
565
566 If a client can resolve the Capability identifier into a description then the client may use the information in the description to display a human readable name and description of the Capability:
567
568 \begin{itemize}
569 \item Access data using openstack
570 \end{itemize}
571
572 \subsubsection{Standard capabilities}
573 \label{subsubsec:standard capabilities}
574 Capability URIs and CapabilityDescriptions for the core set of Capabilities are registered under a StandardKeyEnumeration resource \citep{std:STDREGEXT} in the IVOA registry with the resource identifier ivo://ivoa.net/vospace/core.. The following URIs SHALL be used to represent the service capabilities:
575
576 \begin{itemize}
577 \item ivo://ivoa.net/vospace/core\#vospace-1.0 SHALL be used as the capability URI for a VOSpace 1.0 service
578 \item ivo://ivoa.net/vospace/core\#vospace-1.1 SHALL be used as the capability URI for a VOSpace 1.1 service
579 \item ivo://ivoa.net/vospace/core\#vospace-2.0 SHALL be used as the capability URI for a VOSpace 2.0 service
580 \item ivo://ivoa.net/vospace/core\#vospace-2.1 SHALL be used as the capability URI for a VOSpace 2.1 service
581 \end{itemize}
582 If a service implementation supports more than one version of the VOSpace interface then these capability URIs can be used with a VOSpace service to identify different VOSpace capabilities for a node.
583
584 One use case for this would be a VOSpace 2.1 client talking to a service that implements both VOSpace 2.0 and VOSpace 2.1, where the client is acting on behalf of a third party agent that only understands VOSpace 2.0. In this case, the client can use the information in the VOSpace 2.0 capability to direct the third party agent to the VOSpace 2.0 endpoint.
585
586 Other standard service interfaces will also be registered, e.g.
587
588 \begin{itemize}
589 \item Cone Search
590 \item SIAP
591 \item SSAP
592 \item TAP
593 \end{itemize}
594
595 However, this is not intended to be a closed list and different implementations are free to define and use their own Capabilities.
596
597 \subsection{Views}
598 \label{subsec:views}
599 A View describes the data formats and contents available for importing or exporting data to or from a VOSpace node.
600
601 The metadata for a DataNode contains two lists of Views.
602
603 \begin{itemize}
604 \item \emph{accepts}: is a list of Views that the service can accept for importing data into the Node
605 \item \emph{provides}: is a list of Views that the service can provide for exporting data from Node
606 \end{itemize}
607
608 A View representation SHALL have the following members:
609
610 \begin{itemize}
611 \item \emph{uri}: an optional boolean flag to indicate that the View preserves the original bit pattern of the data
612 \item \emph{original}: a set of name-value pairs that can be used to specify additional arguments for the View
613 \end{itemize}
614
615 \subsubsection{Example view use cases}
616 \label{subsubsec:example view use cases}
617 A simple VOSpace system that stores data as a binary files can just return the contents of the original file. The client supplies a View identifier when it imports the data, and the service uses this information to describe the data to other clients.
618
619 A file based system can use the special case identifier
620 \begin{verbatim}
621 ivo://ivoa.net/vospace/core#anyview
622 \end{verbatim}
623 to indicate that it will accept any data format or View for a Node.
624
625 For example:
626
627 \begin{itemize}
628 \item A client imports a file into the service, specifying a View to describe the file contents
629 \item The service stores the data as a binary file and keeps a record of the View
630 \item The service can then use the View supplied by the client to describe the data to other clients
631 \end{itemize}
632
633 This type of service is not required to understand the imported data, or to verify that it contents match the View, it treats all data as binary files.
634
635 \paragraph{Database store}
636 A VOSpace system that stores data in database tables would need to be able to understand the data format of an imported file in order to parse the data and store it correctly. This means that the service can only accept a specific set of Views, or data formats, for importing data into the Node.
637
638 In order to tell the client what input data formats it can accept, the service publishes a list of specific Views in the accepts list for each Node.
639
640 On the output side, a database system would not be able to provide access to the original input file. The contents of file would have been transferred into the database table and then discarded. The system has to generate the output results from the contents of the database table.
641
642 In order to support this, the service needs to be able to tell the client what Views of the data are available.
643
644 A database system may offer access to the table contents as either VOTable or FITS files, it may also offer zip or tar.gz compressed versions of these. In which case the system needs to be able to express nested file formats such as ``zip containing VOTable'' and ``tar.gz containing FITS''.
645
646 A service may also offer subsets of the data. For example, a work flow system may only want to look at the table headers to decide what steps are required to process the data. If the table contains a large quantity of data, then downloading the whole contents just to look at the header information is inefficient. To make this easier, a database system may offer a 'metadata only' View of the table, returning a VOTable or FITS file containing just the metadata headers and no rows.
647
648 So our example service may want to offer the following Views of a database table:
649
650 \begin{itemize}
651 \item Table contents as FITS
652 \item Table contents as VOTable
653 \item Table contents as zip containing FITS
654 \item Table contents as zip containing VOTable
655 \item Table contents as tar.gz containing FITS
656 \item Table contents as tar.gz containing VOTable
657 \item Table metadata as FITS
658 \item Table metadata as VOTable
659 \end{itemize}
660
661 The service would publish this information as a list of Views in the provides section of the metadata for each Node.
662
663 The VOSpace specification does not mandate what Views a service must provide. The VOSpace specification is intended to provide a flexible mechanism enabling services to describe a variety of different Views of data. It is up to the service implementation to decide what Views of the data it can accept and provide.
664
665 \subsubsection{View identifiers}
666 \label{subsubsec:view identifiers}
667 Every new type of View SHALL require a unique URI to identify the View and its content.
668
669 The rules for the View identifiers are similar to the rules for namespace URIs in XML schema. The only restriction is that it SHALL be a valid (unique) URI.
670
671 \begin{itemize}
672 \item An XML schema namespace identifier can be just a simple URN, e.g. urn:my-namespace
673 \item Within the IVOA, the convention for namespace identifiers is to use a HTTP URL pointing to the namespace schema, or a resource describing it
674 \end{itemize}
675
676 The current VOSpace schema defines View identifiers as anyURI. The only restriction is that it SHALL be a valid (unique) URI.
677
678 \begin{itemize}
679 \item A View URI can be a simple URN, e.g. urn:my-view
680 \end{itemize}
681
682 This may be sufficient for testing and development on a private system, but it is not scalable for use on a public service.
683
684 For a production system, any new Views SHOULD have unique URIs that can be resolved into to a description of the View.
685
686 Ideally, these should be IVO registry URIs that point to a description registered in the IVO registry:
687
688 \begin{itemize}
689 \item ivo://my-registry/vospace/views\#my-view
690 \end{itemize}
691
692 Using an IVO registry URI to identify Views has two main advantages:
693
694 \begin{itemize}
695 \item IVO registry URIs are by their nature unique, which makes it easy to ensure that different teams do not accidentally use the same URI
696 \item If the IVO registry URI points to a description registered in the IVO registry, this provides a mechanism to discover what the View contains
697 \end{itemize}
698
699 \subsubsection{View descriptions}
700 \label{subsubsec:view descriptions}
701 If the URI for a particular View is resolvable, i.e. an IVO registry identifier or a HTTP URL, then it SHOULD point to an XML resource that describes the View.
702
703 A ViewDescription SHOULD describe the data format and/or content of the view.
704
705 A ViewDescription SHOULD have the following members:
706
707 \begin{itemize}
708 \item \emph{uri}: the formal URI of the View
709 \item \emph{DisplayName}: a simple display name of the View.
710 \item \emph{Description}: a text block describing the data format and content of the View.
711 \end{itemize}
712
713 A ViewDescription MAY have the following optional members:
714
715 \begin{itemize}
716 \item \emph{MimeType}: the standard MIME type of the View, if applicable
717 \item \emph{Parameters}: a list of required and option parameters the view accepts, if applicable
718 \end{itemize}
719
720 However, at the time of writing, the schema for registering ViewDescriptions in the IVO registry has not been finalized.
721
722 \paragraph{UI Display name}
723 If a client is unable to resolve a View identifier into a description, then it MAY just display the identifier as a text string:
724
725 \begin{itemize}
726 \item Download as urn:table.meta.fits
727 \end{itemize}
728
729 If the client can resolve the View identifier into a description, then the client MAY use the information in the description to display a human readable name and description of the View:
730
731 \begin{itemize}
732 \item Download table metadata as FITS header
733 \end{itemize}
734
735 \paragraph{Mime Types}
736 If a VOSpace service provides HTTP access to the data contained in a Node, then if the ViewDescription contains a MimeType field, this SHOULD be included in the appropriate header field of the HTTP response.
737
738 \subsubsection{Default views}
739 \label{subsubsec:default views}
740 The following standard URIs are registered under a StandardKeyEnumeration resource \citep{std:STDREGEXT} in the IVOA registry with the resource identifier ivo://ivoa.net/vospace/core. They SHALL be used to refer to the default import and export views:
741
742 \begin{itemize}
743 \item ivo://ivoa.net/vospace/core\#anyview SHALL be used as the view URI to indicate that a service will accept any view for an import operation
744 \item ivo://ivoa.net/vospace/core\#binaryview SHALL be used as the view URI to import or export data as a binary file
745 \item ivo://ivoa.net/vospace/core\#defaultview SHALL be used by a client to indicate that the service should choose the most appropriate view for a data export
746 \end{itemize}
747
748 \paragraph{Default import view}
749 If a client imports data using this view, the data SHALL be treated as a binary BLOB, and stored as is with no additional processing. This is equivalent to the application/binary MIME type.
750
751 Note, this view is OPTIONAL, and the service may throw a ViewNotSupported exception if it does not accept this view. In particular, this view cannot be used to import data into a StructuredDataNode as the service needs to know about and understand the data format to be able to create the StructuredDataNode.
752
753 Note, this view is only valid for the data import operations, pullToVoSpace and pushToVoSpace. If this view is requested in an export operation, pullFromVoSpace and pushToVoSpace, then the service SHOULD throw a ViewNotSupported exception.
754
755 \paragraph{Default export view}
756 If a client requests data using this view, the server SHALL choose whichever of the available views (the server) thinks is the most appropriate, based on how the data is stored. In a simple file-based system, this will probably be the same format that the data was originally imported in. In a database table system, this will probably either be VOTable or CVS, depending on the level of metadata available.
757
758 Note, this view is OPTIONAL, and the server may throw a ViewNotSupported exception if it does not provide this view. However, in most cases, it is expected that a service would be able to select an appropriate 'default' format for data held within the service.
759
760 Note, this view is only valid for the data export operations, pullFromVoSpace and pushFromVoSpace. If this view is requested in an import operation, pullToVoSpace and pushToVoSpace, then the service SHOULD throw a ViewNotSupported fault.
761
762 \subsubsection{Container views}
763 \label{subsubsec:container views}
764 In VOSpace 2.1, a view of a ContainerNode describes the data representation (format) of a file or data stream that represents the combined contents of the node and its children. If the view describes an archive format (tar, zip, etc.) then a service that accepts this view (format) for a ContainerNode SHALL provide access to the archive contents as children nodes of the container. Whether or not the service actually unpacks the archive is implementation dependent but the service SHALL behave as though it has done so. For example, a client may want to upload a tar file containing several images to a VOSpace service. If they associate it with (upload it to) a (Un)structuredDataNode then it will be treated as a blob and its contents will be not be available. However, if they upload it to a ContainerNode with an accepts view of "tar" then the image files within the tar file will be represented as children nodes of the ContainerNode and accessible like any other data object within the space.
765
766 If a service provides an archive format (tar, zip, etc.) view of a ContainerNode then the service SHALL package the contents of the container and all its child nodes in the specified format.
767
768 \subsection{Protocols}
769 \label{subsec:protocols}
770 A Protocol describes the parameters required to perform a data transfer using a particular protocol.
771
772 A Protocol representation SHALL have the following members:
773
774 \begin{itemize}
775 \item \emph{uri}: the Protocol identifier
776 \item \emph{endpoint}: the endpoint URL to use for the data transfer additional arguments required for the transfer
777 \end{itemize}
778
779 A protocol representation MAY have the following members:
780
781 \begin{itemize}
782 \item \emph{param}: A list of name-value pairs that specify any additional arguments required to support the protocol
783 \item \emph{securityMethod}: The requested (and/or resulting) authentication type
784 \end{itemize}
785
786 Note: endpoint will only contain a value after the response from the service is received.
787
788 \subsubsection{Protocol identifiers}
789 \label{subsubsec:protocol identifiers}
790 Every new type of Protocol requires a unique URI to identify the Protocol and how to use it.
791
792 The rules for the Protocol identifiers are similar to the rules for namespace URIs in XML schema. The only restriction is that it SHALL be a valid (unique) URI
793
794 \begin{itemize}
795 \item An XML schema namespace identifier can be just a simple URN, e.g. urn:my-namespace
796 \item Within the IVOA, the convention for namespace identifiers is to use a HTTP URL pointing to the namespace schema, or a resource describing it
797 \end{itemize}
798
799 The current VOSpace schema defines Protocol identifiers as anyURI. The only restriction is that it SHALL be a valid (unique) URI.
800
801 \begin{itemize}
802 \item A Protocol URI can be a simple URN, e.g. urn:my-protocol
803 \end{itemize}
804
805 This may be sufficient for testing and development on a private system, but it is not scalable for use on a public service.
806
807 For a production system, any new Protocols SHOULD have unique URIs that can be resolved into to a description of the Protocol.
808
809 Ideally, these should be IVO registry URIs that point to a description registered in the IVO registry:
810
811 \begin{itemize}
812 \item \begin{verbatim}ivo://my-registry/vospace/protocols#my-protocol\end{verbatim}
813 \end{itemize}
814
815 Using an IVO registry URI to identify Protocols has two main advantages:
816
817 \begin{itemize}
818 \item IVO registry URIs are by their nature unique, which makes it easy to ensure that different teams do not accidentally use the same URI
819 \item If the IVO registry URI points to a description registered in the IVO registry, this provides a mechanism to discover how to use the Protocol
820 \end{itemize}
821
822 \subsubsection{Protocol descriptions}
823 \label{subsubsec:protocol descriptions}
824 If the URI for a particular Protocol is resolvable, i.e. an IVO registry identifier or a HTTP URL, then it SHOULD point to an XML resource that describes the Protocol.
825
826 A ProtocolDescription SHOULD describe the underlying transport protocol, and how it should be used in this context.
827
828 A ProtocolDescription SHOULD have the following members:
829
830 \begin{itemize}
831 \item \emph{uri}: the formal URI of the Protocol
832 \item \emph{DisplayName}: A simple display name of the Protocol
833 \item \emph{Description}: Text block describing describing the underlying transport protocol, and how it should be used in this context
834 \end{itemize}
835
836 However, at the time of writing, the schema for registering ProtocolDescriptions in the IVO registry has not been finalized.
837
838 \paragraph{UI display name}
839
840 If a client is unable to resolve a Protocol identifier into a description, then it MAY just display the identifier as a text string:
841
842 \begin{itemize}
843 \item Download using urn:my-protocol
844 \end{itemize}
845
846 If the client can resolve the Protocol identifier into a description, then the client MAY use the information in the description to display a human readable name and description of the Protocol:
847
848 \begin{itemize}
849 \item Download using standard HTTP GET
850 \end{itemize}
851
852 \subsubsection{Standard protocols}
853 \label{subsubsec:standard protocols}
854 Protocol URIs and ProtocolDescriptions for the core set of standard transport protocols are registered under a StandardKeyEnumeration resource \citep{std:STDREGEXT} in the IVOA registry with the resource identifier ivo://ivoa.net/vospace/core. The following URIs SHALL be used to represent the standard protocols:
855
856 \begin{itemize}
857 \item \begin{verbatim}ivo://ivoa.net/vospace/core#httpget\end{verbatim} SHALL be used as the protocol URI for a HTTP GET transfer
858 \item \begin{verbatim}ivo://ivoa.net/vospace/core#httpput\end{verbatim} SHALL be used as the protocol URI for a HTTP PUT transfer
859 \item \begin{verbatim}ivo://ivoa.net/vospace/core#httpsget\end{verbatim} SHALL be used as the protocol URI for a HTTP GET transfer over a Secure Socket Layer (SSL)
860 \item \begin{verbatim}ivo://ivoa.net/vospace/core#httpsput\end{verbatim} SHALL be used as the protocol URI for a HTTP PUT transfer over a Secure Socket Layer (SSL)
861 \end{itemize}
862
863 However, this is not intended to be a closed list, different implementations are free to define and use their own transfer Protocols and authentication types.
864
865 \subsubsection{Custom protocols}
866 \label{subsubsec:custom protocols}
867 There are several use cases where a specific VOSpace implementation may want to define and use a custom VOSpace transfer Protocol, either extending an existing Protocol, or defining a new one.
868
869 \paragraph{SRB Gateway}
870 One example would be a VOSpace service that was integrated with a SRB (Storage Resource Broker) system. In order to enable the service to use the native SRB transport protocol to transfer data, the service providers would need to register a new ProtocolDescription to represent the SRB transport protocol.
871
872 The ProtocolDescription would refer to the technical specification for the SRB transport protocol, and define how it should be used to transfer data to and from the VOSpace service.
873
874 Clients that do not understand the SRB transport protocol would not recognize the URI for the SRB Protocol, and would ignore Transfer options offered using this Protocol.
875
876 Clients that were able to understand the SRB transport protocol would recognize the URI for the SRB Protocol, and could use the 'srb://..' endpoint address in a Protocol option to transfer data using the SRB transport protocol.
877
878 Enabling different groups to define, register and use their own custom Protocols in this way means that support for new transport protocols can be added to VOSpace systems without requiring changes to the core VOSpace specification.
879
880 In this particular example, it is expected that one group within the IVOA will work with the SRB team at SDSC to define and register the Protocol URI and ProtocolDescription for using the SRB protocol to transfer data to and from VOSpace systems.
881
882 Other implementations that plan to use the SRB transport protocol in the same way could use the same Protocol URI and ProtocolDescription to describe data transfers using the SRB transport protocol.
883
884 The two implementations would then be able use the common Protocol URI to negotiate data transfers using the SRB transport protocol.
885
886 \paragraph{Local NFS transfers}
887
888 Another example of a custom Protocol use case would to transfer data using the local NFS file system within an institute.
889
890 If an institute has one or more VOSpace services co-located with a number of data processing applications, all located within the same local network, then it would be inefficient to use HTTP GET and PUT to transfer the data between the services if they could all access the same local file system.
891
892 In this case, the local system administrators could register a custom ProtocolDescription which described how to transfer data using their local NFS file system.
893
894 \begin{itemize}
895 \item \begin{verbatim}ivo://my.institute/vospace/protocols#internal-nfs\end{verbatim}
896 \end{itemize}
897
898 Data transfers using this Protocol would be done using file:// URLs pointing to locations within the local NFS file system:
899
900 \begin{itemize}
901 \item \begin{verbatim}file:///net/host/path/file\end{verbatim}
902 \end{itemize}
903
904 These URLs would only have meaning to services and applications located within the local network, and would not be usable from outside the network.
905
906 Services and applications located within the local network would be configured to recognize the custom Protocol URI, and to use local file system operations to move files within the NFS file system.
907
908 Services and applications located outside local network would not recognize the custom Protocol URI and so would not attempt to use the internal file URLs to transfer data.
909
910 Note that in this example the custom Protocol URI and the associated ProtocolDescription refer to data transfers using file URLs within a specific local NFS file system.
911
912 If a different institute wanted to use a similar system to transfer data within their own local network, then they would have to register their own custom Protocol URI and associated ProtocolDescription.
913
914 The two different Protocol URIs and ProtocolDescriptions describe how to use the same underlying transport protocol (NFS) in different contexts.
915
916 Enabling different groups to define, register and use their own custom Protocols in this way means that systems can be configured to use the best available transport protocols for transferring data, without conflicting with other systems who may be using similar a transport protocol in a different context.
917
918 \subsubsection{Security Methods}
919 Each protocol may have an associated securityMethod element that describes the supported authentication method for that protocol.
920
921 For transfer requests, the securityMethod indicates that the client is capable of that authentication method for that protocol. The protocols should be listed in preferred order. It is recommended that the entire list of protocol securityMethod combinations that the client supports be provided.
922
923 The Protocol list in transfer responses represent the protocol and securityMethod combinations that are supported by the server. The server must only list supported combinations. The server may choose to consult the protocol and securityMethod combinations in the transfer request to generate the ordered list of protocols.
924
925 \subsection{Transfers}
926 \label{subsec:transfers}
927 A Transfer describes the details of a data transfer to or from a VOSpace.
928
929 \subsubsection{XML Document Transfers}
930 \label{subsubsec:xml document transfers}
931
932 Transfers can be represented as XML documents. For example:
933
934 \begin{verbatim}
935 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
936 <vos:target>vos://example.com!vospace/myspace/myfile</vos:target>
937 <vos:direction>pushToVoSpace</vos:direction>
938 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpsput">
939 <vos:securityMethod uri="ivo://ivoa.net/sso#tls-with-certificate"/>
940 </vos:protocol>
941 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpput">
942 <vos:securityMethod "uri="http://www.w3.org/Protocols/HTTP/1.0/spec/html#BasicAA"/>
943 </vos:protocol>
944 </vos:transfer>
945 \end{verbatim}
946
947 Clients send transfer XML documents to a VOSpace synchronous or asynchronous UWS transfer endpoint. The VOSpace service SHALL put, in the UWS Job results, a resulting transfer XML document.
948
949 A client initiated UWS Job representation of a Transfer SHALL have the following parameters:
950
951 \begin{itemize}
952 \item \emph{target}: denotes the VOSpace node to/from which data is to be transferred
953 \item \emph{direction}: denotes the direction of a data transfer
954 \begin{itemize}
955 \item It can be a URI for internal data transfers (move and copy operations) or one of: pushToVoSpace, pullToVoSpace, pushFromVoSpace or pullFromVoSpace - for external data transfer.
956 \end{itemize}
957 \item \emph{view}: denotes the requested View
958 \begin{itemize}
959 \item For the transfer to be valid, the specified View must match one of those listed in the accepts or provides list of the Node.
960 \item For an internal data transfer, this parameter is not required.
961 \end{itemize}
962 \item \emph{protocol}: denotes the transfer protocol(s) to use
963 \begin{itemize}
964 \item A transfer may contain more than one protocol with different Protocol URIs.
965 \item Each protocol may contain one or more security methods that can be applied to the protocol. It is recommended that a protocol for each securityMethod be included in the transfer.
966 \item For an internal data transfer, this parameter is not required.
967 \end{itemize}
968 \item \emph{keepBytes}: denotes whether the source object is to be kept in an internal data transfer, i.e. distinguishes between a move and a copy
969 \begin{itemize}
970 \item For an external data transfer, this parameter is not required.
971 \end{itemize}
972 \item \emph{param}: A list of zero or more parameters that specify any additional arguments for the transfer.
973 \begin{itemize}
974 \item Standard Property URIs should be used as the parameter key.
975 \item e.g. Clients may tell the service the size of a file they intend to upload: <vos:param uri="ivo://ivoa.net/vospace/core\#length">1024</vos:param>
976 \end{itemize}
977 \end{itemize}
978
979 This representation will be used as a child of the jobInfo element in a UWS Job representation.
980
981 The service representation of the results of a Transfer SHALL have the following members:
982
983 \begin{itemize}
984 \item \emph{target}: denotes the VOSpace node to/from which data is to be transferred
985 \item \emph{direction}: denotes the direction of a data transfer
986 \begin{itemize}
987 \item It can be a URI for internal data transfers (move and copy operations) or one of: pushToVoSpace, pullToVoSpace, pushFromVoSpace or pullFromVoSpace - for an external data transfer.
988 \end{itemize}
989 \item \emph{view}: A View specifying the requested View
990 \begin{itemize}
991 \item For the transfer to be valid, the specified View must match one of those listed in the accepts or provides list of the Node.
992 \item For an internal data transfer, this parameter is not required.
993 \end{itemize}
994 \item \emph{protocol}: denotes the transfer protocol(s) to use
995 \begin{itemize}
996 \item A transfer may contain more than one protocol with different Protocol URIs.
997 \item A Transfer may contain more than one Protocol element with the same Protocol URI with different endpoints
998 \item Each protocol on the result must contain an endpoint.
999 \item Each protocol may contain one or more security methods that can be applied to the protocol.
1000 \item For an internal data transfer, this parameter is not required.
1001 \end{itemize}
1002 \item \emph{param}: parameters related to the transfer
1003 \begin{itemize}
1004 \item A transfer may contain zero or more transfer parameters.
1005 \end{itemize}
1006 \end{itemize}
1007
1008 \subsubsection{URL Parameter Transfers}
1009 \label{subsubsec:url parameter transfers}
1010 A simplified and restricted method of transfer negotiation makes use of URL query string parameters rather than XML documents. Parameter based transfer negotiation support is optional and is limited to the UWS synchronous transfer endpoint. The following is an example URL for a parameter transfer negotiation:
1011
1012 \begin{verbatim}
1013 http://server.example.com/vospace/synctrans?
1014 TARGET=vos://example.com~vospace/mydata1&
1015 DIRECTION=pullFromVoSpace&
1016 PROTOCOL=ivo://ivoa.net/vospace/core#httpget
1017 \end{verbatim}
1018
1019 The following parameters MUST be supplied by the client requesting a transfer:
1020
1021 \begin{itemize}
1022 \item \emph{TARGET}: denotes the VOSpace node to/from which data is to be transferred
1023 \item \emph{DIRECTION}: denotes the direction of a data transfer
1024 \begin{itemize}
1025 \item With parameter based negotiation, only pushToVoSpace and pullFromVoSpace are allowed as values for DIRECTION.
1026 \end{itemize}
1027 \item \emph{PROTOCOL}: denotes the transfer protocol(s) to use.
1028 \begin{itemize}
1029 \item With parameter based negotiation, clients MUST provide exactly one PROTOCOL parameter.
1030 \end{itemize}
1031 \end{itemize}
1032
1033 The following parameters MAY be supplied by the client requesting a transfer:
1034
1035 \begin{itemize}
1036 \item \emph{VIEW}: The standard URI of the view to use. If no view is provided the service SHALL use the default view.
1037 \item \emph{SECURITYMETHOD}: The standard URI of the security method that can be used for the supplied PROTOCOL.
1038 \item \emph{REQUEST=redirect}: If the supplied, the service SHALL respond with an HTTP redirect to an endpoint for the PROTOCOL.
1039 \begin{itemize}
1040 \item This parameter is only applicable when the value of the DIRECTION parameter is \emph{pullFromVoSpace}.
1041 \end{itemize}
1042 \end{itemize}
1043
1044 Parameter values must be URL-encoded.
1045
1046 Upon receipt of a parameter based transfer negotiation request to the synchronous transfer endpoint, the service SHALL reply with a XML representation of the transfer results in the response body. The only exception to this is when the DIRECTION is \emph{pullFromVoSpace} and the REQUEST=redirect parameter is provided and set to \emph{true}, in which case the service SHALL respond with an HTTP redirect to the endpoint of the supplied PROTOCOL.
1047
1048 \subsubsection{Service-initiated transfers}
1049 \label{subsubsec:service-initiated transfers}
1050 Two of the external data transfers (pullToVoSpace and pushFromVoSpace) rely on the server performing the data transfer itself.
1051
1052 The client constructs a Job request containing details of the View and one or more Protocol elements with valid endpoint addresses.
1053
1054 The service MAY ignore Protocols with URIs that it does not recognize.
1055
1056 If the server is unable to handle any of the requested Protocols in a Transfer request, then it SHALL respond with a fault.
1057
1058 The order of the Protocols in the request indicates the order of preference that the client would like the server to use. However, this is only a suggestion, and the server is free to use its own preferences to select which Protocol it uses first.
1059
1060 The service selects the first Protocol it wants to use from the list and attempts to transfer the data using the Protocol endpoint.
1061
1062 If the first attempt fails, the server may choose another Protocol from the list and re-try the transfer using that Protocol endpoint. The status flag will be updated to reflect this.
1063
1064 The server may attempt to transfer the data using any or all of the Protocols in the list until either, the data transfer succeeds, or there are no more Protocol options left.
1065
1066 The server SHALL be allowed to only use each Protocol option once. This allows a data source to issue one time URLs for a Transfer, and cancel each URL once it has been used.
1067
1068 Once one of the Protocol options succeeds the transfer SHALL be considered to have completed - the status flag needs to be updated to reflect this -, and the server is not allowed to use any of the remaining Protocol options. This allows a data source to issue a set of one time URLs for a transfer, and to cancel any unused URLs once the transfer has been completed.
1069
1070 Some Protocols MAY require the service to call a callback address when a data transfer completes. This behavior is specific to the Protocol, and SHOULD be defined in the ProtocolDescription.
1071
1072 If none of the Protocol options succeed, then the transfer SHALL be considered to have failed, and the service SHALL return a fault containing details of the Protocol options it tried. The status flag will be updated to reflect this.
1073
1074 \subsubsection{Client-initiated transfers}
1075 \label{subsubsec:client-initiated transfers}
1076 Two of the VOSpace external transfer methods (pushToVoSpace and pullFromVoSpace) rely on an external actor performing the data transfer outside the scope of the service call.
1077
1078 In these methods, the client sends a Job request to the server which SHOULD contain details of the View and one or more protocol parameters.
1079
1080 In effect, the client is sending a list of Protocols that it (the client) wants to use for the transfer.
1081
1082 The service MAY ignore Protocols with URIs that it does not recognize.
1083
1084 The service selects the Protocols from the request that it is capable of handling, and builds a Transfer results response containing the selected Protocol elements filling in valid endpoint addresses for each of them.
1085
1086 If available, the service may choose to consult the securityMethod in the Protocols to construct correct endpoints.
1087
1088 The order of the Protocol elements (and their corresponding security methods) in the request indicates the order of preference that the client would like to use. However, this is only a suggestion, and the server is free to use its own preferences when generating the list of Protocols in the response.
1089
1090 In effect, the server is responding with the subset of the requested Protocols that it (the server) is prepared to offer.
1091
1092 If the server is unable to accept any of the requested Protocols, then it SHALL respond with a fault.
1093
1094 On receipt of the response, the client can use the list of Protocols itself, or pass them on to another agent to perform the data transfer on its behalf.
1095
1096 The agent MAY ignore Protocols URIs that it does not recognize.
1097
1098 The agent selects the first Protocol it wants to use from the list and attempts to transfer the data using the Protocol endpoint. The status flag will be updated to reflect this.
1099
1100 If the first attempt fails, the agent MAY choose another Protocol from the list and re-try the transfer using that Protocol endpoint.
1101
1102 The agent MAY attempt to transfer the data using any or all of the Protocols in the list until either, the data transfer succeeds, or there are no more Protocol options left.
1103
1104 The agent SHALL be allowed to only use each Protocol option once. This allows a data source to issue one time URLs for a Transfer, and cancel each URL once it has been used.
1105
1106 Once one of the Protocol options succeeds the transfer SHALL be considered to have completed and the status flag will be updated correspondingly. The agent is not allowed to use any of the remaining unused Protocol options. This allows a data source to issue a set of one time URLs for a transfer, and to cancel any unused URLs once the transfer has been completed.
1107
1108 Some Protocols MAY require the agent to call a callback address when a data transfer completes. This behavior is specific to the Protocol, and SHOULD be defined in the ProtocolDescription.
1109
1110 If none of the Protocol options succeed, then the transfer SHALL be considered to have failed and the status will be updated.
1111
1112 % Searches have been removed in version 2.1 due to no implementations
1113 % \subsection{Searches}
1114 % \label{subsec:searches}
1115 % A Search describes the details of data objects in the space which meet specified search criteria, i.e. that are the results of a submitted search request.
1116 %
1117 % A UWS Job representation of a Search SHALL have the following parameters:
1118 %
1119 % \begin{itemize}
1120 % \item \emph{uri}: An OPTIONAL identifier indicating from which item to continue a search
1121 % \item \emph{limit}: An OPTIONAL limit indicating the maximum number of results in the response
1122 % \begin{itemize}
1123 % \item No limit indicates a request for an unpaged list. However the server MAY still impose its own limit on the size of an individual response, splitting the results into more than one page if required
1124 % \end{itemize}
1125 % \item \emph{detail}: The level of detail in the results
1126 % \begin{itemize}
1127 % \item min: The list contains the minimum detail for each Node with all optional parts removed - the node type should be returned
1128 % \begin{itemize}
1129 % \item e.g. \emph{<node uri="vos://service/name" xs:type="Node"/>}
1130 % \end{itemize}
1131 % \item max : The list contains the maximum detail for each Node, including any xs:type specific extensions
1132 % \item properties : The list contains a basic node element with a list of properties for each Node with no xs:type specific extensions.
1133 % \end{itemize}
1134 % \item \emph{matches}: An OPTIONAL search string consisting of properties and values to match against and joined in conjunction (and) or disjunction (or).
1135 % \begin{itemize}
1136 % \item Each property-value pair consists of the uri identifying a particular property and a regular expression against which the property values are to be matched: `uri' = `regex'
1137 % \item The match pairs can be combined in conjunction and/or disjunction using 'and' and 'or' respectively. For example: (property1 = `value1' and property2 = `value2') or property3 = `value3'.
1138 % \item The regex syntax SHALL comply with POSIX conventions.
1139 % \end{itemize}
1140 % \item \emph{node}: An OPTIONAL URI(s) identifying the starting node for a search, i.e., the matches constraints are applied to this node and its children
1141 % \end{itemize}
1142 %
1143 % This representation will be used as a child of the jobInfo element in a UWS Job representation. For example:
1144 %
1145 % \begin{verbatim}
1146 % <uws:jobInfo>
1147 % <vos:search>
1148 % <vos:detail>properties</vos:detail>
1149 % <vos:matches>
1150 % ivo://ivoa.net/vospace/core#description="galax"
1151 % </vos:matches>
1152 % <vos:search>
1153 % <uws:jobInfo>
1154 % \end{verbatim}
1155 %
1156 % The representation of the results of a Search SHALL have the following members:
1157 %
1158 % \begin{itemize}
1159 % \item \emph{nodes}: A list containing zero or more Nodes of appropriate detail identifying the target URIs meeting the search criteria
1160 % \end{itemize}
1161
1162 \subsection{REST bindings}
1163 \label{subsec:rest bindings}
1164 In a REST (Representational State Transfer) binding of VOSpace, each of the objects defined below is available as a web resource with its own URI.
1165
1166 \vspace{3mm}
1167 \begin{tabular}{ l p{4cm} }
1168 \hline
1169 /properties & the properties employed in the space \\
1170 \hline
1171 /views & the views employed in the space \\
1172 \hline
1173 /protocols & the protocols employed in the space \\
1174 % \hline
1175 % /searches & the searches of the space \\
1176 \hline
1177 /nodes/(node-path) & a Node under the nodes of the space \\
1178 \hline
1179 /transfers & asynchronous transfers for the space \\
1180 \hline
1181 /synctrans & synchronous transfers for the space \\
1182 \hline
1183 /transfers/(job-id)/results/transferDetails & the resulting transfer details \\
1184 \hline
1185 \end{tabular}
1186 \vspace{3mm}
1187
1188 These names are part of the VOSpace 2.1 standard.
1189
1190 The following Nodes, appearing as part of a node-path, are reserved:
1191
1192 \begin{itemize}
1193 \item .auto indicates that the service should auto-generate an endpoint URI to replace this placeholder (Note: that this is an OPTIONAL feature of a service)
1194 \item .null indicates an endpoint that discards all data written to it and provides no data when read from, i.e. a bit bucket
1195 \end{itemize}
1196
1197 The standardID for the service is: ivo://ivoa.net/std/VOSpace/v2.1. Available resources will then just be ivo://ivoa.net/std/VOSpace/v2.1\#<resourceName>, e.g., ivo://ivoa.net/std/VOSpace/v2.1\#nodes.
1198
1199 \section{Access Control}
1200 \label{sec:access control}
1201 VOSpace implementations may support a number of authentication methods including:
1202
1203 \begin{itemize}
1204 \item no authentication (anonymous clients)
1205 \item digital signatures with X.509 client certificates
1206 \item OAuth (http://oauth.net)
1207 \end{itemize}
1208
1209 For a full list of authentication methods and the associated standardIDs please refer to the document: \href{http://www.ivoa.net/documents/latest/SSOAuthMech.html}{IVOA Single-Sign-On Profile: Authentication Mechanisms}.
1210
1211 When a client is requesting a transfer from the service, the authentication type (securityMethod) may be supplied along side the list of transfer protocols. The \emph{securityMethod} is specified by standardID. If the service supports the requested type, it may base the construction of the endpoint URL for data transfer from this information. (Services may encounter situations when the URL for data transfer will depend on the authentication type the client wishes to use.)
1212
1213 For backwards compatibility support, services SHALL include the securityMethod element in the transfer response if and only if a securityMethod was provided by the client in the protocol.
1214
1215 The access control policy for a VOSpace is defined by the implementor of that space according to the use cases for which the implementation is intended.
1216
1217 A human-readable description of the implemented access policy must be declared in the registry metadata for the space.
1218
1219 These are the most probable access policies:
1220
1221 \begin{itemize}
1222 \item No authorization is required, but clients must authenticate an identity (for logging purposes) in each request to the space
1223 \item Clients may not create or change nodes (i.e. the contents of the space are fixed by the implementation or set by some interface other than VOSpace), but any client can read any node without authentication
1224 \item Nodes are considered to be owned by the user who created them. Only the owner can operate on a node
1225 \item Node authorization is similar to that of Linux file system permission handling with ownership and group membership.
1226 \end{itemize}
1227
1228 No operations to modify the access policy (e.g. to set permissions on an individual node) are included in this standard. Later versions may add such operations.
1229
1230 Where the access policy requires authentication of callers, the VOSpace service SHALL support one of the authentication methods defined in the IVOA Single Sign On Profile.
1231
1232 \section{Web service operations}
1233 \label{sec:web service operations}
1234
1235 A VOSpace 2.1 service SHALL be a RESTful service with the operations listed in this section.
1236
1237 \paragraph{Notes}
1238 \begin{itemize}
1239 \item The URL http://(rest-endpoint)/nodes denotes the URL of the top node in the VOSpace. The URL http://(rest-endpoint)/nodes/(path) denotes a specific node within the VOSpace.
1240 \item When representing a Fault, the exact specified fault name SHALL be used. If this is followed by some details, the fault SHALL be separated from the subsequent characters by whitespace.
1241 \item If the service is able to detect an internal system failure (associated with an HTTP 500 status code) then it should indicate this as described below if possible.
1242 \item When clients POST or PUT XML documents (such as transfer documents), the Content-Type should be set to \emph{text/xml}
1243 \end{itemize}
1244
1245 \subsection{Service metadata}
1246 \label{subsec:service metadata}
1247 These operations return comprehensive lists of service-level metadata, e.g. all protocols supported by the service. Individual nodes within a service, however, may not necessarily support all of these, i.e. only container nodes may support archive formats such as zip or tar.
1248
1249 \subsubsection{getProtocols}
1250 \label{subsubsec:getprotocols}
1251 Get a list of the transfer Protocols supported by the VOSpace service
1252
1253 \paragraph{Request}
1254 A HTTP request to http://rest-endpoint/protocols
1255
1256 \paragraph{Response}
1257 \subparagraph{Status code} A HTTP 200 status code
1258 \subparagraph{Body}
1259 A Protocols representation giving:
1260 \begin{itemize}
1261 \item accepts: A list of Protocols that the service SHALL accept
1262 \begin{itemize}
1263 \item In this context `accepting a protocol' means that the service SHALL act as a client for the protocol
1264 \item e.g. `accepting httpget' means the service can read data from an external HTTP web server
1265 \end{itemize}
1266 \item provides: A list of Protocols that the service SHALL provide
1267 \begin{itemize}
1268 \item In this context `providing a protocol' means that the service SHALL act as a server for the protocol
1269 \item e.g. `providing httpget' means the service can act as a http web server
1270 \end{itemize}
1271 \end{itemize}
1272
1273 \paragraph{Faults}
1274 \begin{itemize}
1275 \item The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity body if the operation fails
1276 \end{itemize}
1277
1278 \paragraph{Example}
1279 Get the VOSpace protocols
1280 \\[5px]
1281 \noindent
1282 Request:
1283 \begin{lstlisting}
1284 > curl -v http://server.example.com/vospace/protocols
1285 \end{lstlisting}
1286 Response:
1287 \begin{lstlisting}
1288 > GET /vospace/protocols HTTP/1.1
1289 >
1290 < HTTP/1.1 200 OK
1291 < Content-Type: text/xml
1292 <
1293 <vos:protocols xmlns="http://www.ivoa.net/xml/VOSpace/v2.1" xmlns:xs="http://www.w3.org/2001/XMLSchema-instance">
1294 <vos:accepts>
1295 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpget"/>
1296 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpput"/>
1297 </vos:accepts>
1298 <vos:provides>
1299 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpget"/>
1300 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpput"/>
1301 </vos:provides>
1302 </vos:protocols>
1303 \end{lstlisting}
1304
1305 \subsubsection{getViews}
1306 \label{subsubsec:getviews}
1307 Get a list of the Views and data formats supported by the VOSpace service
1308
1309 \paragraph{Request}
1310 A HTTP GET to http://rest-endpoint/views
1311
1312 \paragraph{Response}
1313 \subparagraph{Status code} A HTTP 200 status code
1314 \subparagraph{Body}
1315 A Views representation giving:
1316 \begin{itemize}
1317 \item accepts: A list of Views that the service SHALL accept
1318 \begin{itemize}
1319 \item In this context `accepting a view' means that the service SHALL receive input data in this format
1320 \item A simple file based system may use the reserved View URI ivo://net.ivoa.vospace/views/any to indicate that it can accept data in any format
1321 \end{itemize}
1322 \item provides: A list of Views that the service SHALL provide
1323 \begin{itemize}
1324 \item In this context `providing a view' means that the service SHALL produce output data in this format
1325 \item A simple file based system may use the reserved View URI ivo://net.ivoa.vospace/views/any to indicate that it can provide data in any format
1326 \end{itemize}
1327 \end{itemize}
1328
1329 \paragraph{Faults}
1330 \begin{itemize}
1331 \item The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity body if the operation fails
1332 \end{itemize}
1333
1334 \paragraph{Example}
1335 Get the VOSpace views
1336 \\[5px]
1337 \noindent
1338 Request:
1339 \begin{lstlisting}
1340 > curl -v "http://server.example.com/vospace/views"
1341 \end{lstlisting}
1342 Response:
1343 \begin{lstlisting}
1344 > GET /vospace/views HTTP/1.1
1345 >
1346 < HTTP/1.1 200 OK
1347 < Content-Type: text/xml
1348 <
1349 <vos:views xmlns="http://www.ivoa.net/xml/VOSpace/v2.1" xmlns:xs="http://www.w3.org/2001/XMLSchema-instance">
1350 <vos:accepts>
1351 <vos:view uri="ivo://ivoa.net/vospace/core#anyview"/>
1352 </vos:accepts>
1353 <vos:provides>
1354 <vos:view uri="ivo://ivoa.net/vospace/core#defaultview"/>
1355 </vos:provides>
1356 </vos:views>
1357 \end{lstlisting}
1358
1359 \subsubsection{getProperties}
1360 \label{subsubsec:getproperties}
1361
1362 \paragraph{Request}
1363 A HTTP request to http://rest-endpoint/properties
1364
1365 \paragraph{Response}
1366 \subparagraph{Status code} A HTTP 200 status code
1367 \subparagraph{Body}
1368 A Properties representation including:
1369 \begin{itemize}
1370 \item accepts: A list of identifiers for the Properties that the service SHALL accept and understand. This refers to metadata (Properties) that is implementation dependent but can be used by a client to control operational aspects of the service: for example, a VOSpace implementation might allow individual users to control the permissions on data objects via a Property called ``permissions''. If the VOSpace receives a data object with this Property then it `understands' what this property refers to and can deal with it accordingly.
1371 \item provides: A list of identifiers for the Properties that the service SHALL provide
1372 \item contains: A list of identifiers for all the Properties currently used by Nodes within the service
1373 \end{itemize}
1374
1375 \paragraph{Faults}
1376 \begin{itemize}
1377 \item The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity body if the operation fails
1378 \end{itemize}
1379
1380 \paragraph{Example}
1381 Get the VOSpace properties
1382 \\[5px]
1383 \noindent
1384 Request:
1385 \begin{lstlisting}
1386 > curl -v "http://server.example.com/vospace/properties"
1387 \end{lstlisting}
1388 Response:
1389 \begin{lstlisting}
1390 > GET /vospace/properties HTTP/1.1
1391 >
1392 < HTTP/1.1 200 OK
1393 < Content-Type: text/xml
1394 <
1395 <vos:properties xmlns="http://www.ivoa.net/xml/VOSpace/v2.1" xmlns:xs="http://www.w3.org/2001/XMLSchema-instance">
1396 <vos:accepts>
1397 <vos:property uri="ivo://ivoa.net/vospace/core#title"/>
1398 <vos:property uri="ivo://ivoa.net/vospace/core#creator"/>
1399 <vos:property uri="ivo://ivoa.net/vospace/core#description"/>
1400 </vos:accepts>
1401 <vos:provides>
1402 <vos:property uri="ivo://ivoa.net/vospace/core#availableSpace"/>
1403 <vos:property uri="ivo://ivoa.net/vospace/core#httpput"/>
1404 </vos:provides>
1405 <vos:contains>
1406 <vos:property uri="ivo://ivoa.net/vospace/core#availableSpace"/>
1407 <vos:property uri="ivo://ivoa.net/vospace/core#title"/>
1408 <vos:property uri="ivo://ivoa.net/vospace/core#creator"/>
1409 <vos:property uri="ivo://ivoa.net/vospace/core#description"/>
1410 </vos:contains>
1411 </vos:properties>
1412 \end{lstlisting}
1413
1414 \subsection{Creating and manipulating data nodes}
1415 \label{subsec:creating and manipulating data nodes}
1416
1417 \subsubsection{createNode}
1418 \label{subsubsec:createnode}
1419 Create a new node at a specified location
1420
1421 \paragraph{Request}
1422 A HTTP PUT of a node representation to path of the node to be created on the /nodes resource:
1423 \begin{verbatim}
1424 http://server.example.com/vospace/nodes/<path to node>
1425 \end{verbatim}
1426 The node representation is template Node (as defined in section \ref{subsec:nodes and node types}) for the node to be created.
1427
1428 A valid uri attribute SHALL be required. The name .auto is a reserved URI to indicate an auto-generated URI for the destination, i.e. given the following URI vos://service/path/.auto a service SHOULD create a new unique URI for the node within vos://service/path.
1429
1430 If the node path of the uri in the node representation does not match the node path in the HTTP PUT URL the service SHALL return an error.
1431
1432 If the Node xs:type is not specified then a generic node of type Node is implied.
1433
1434 The permitted values of xs:type are:
1435
1436 \begin{itemize}
1437 \item vos:Node
1438 \item vos:DataNode
1439 \item vos:UnstructuredDataNode
1440 \item vos:StructuredDataNode
1441 \item vos:ContainerNode
1442 \item vos:LinkNode
1443 \end{itemize}
1444
1445 When creating a new Node the service MAY substitute a valid subtype, i.e. If xs:type is set to vos:DataNode then this may be implemented as a DataNode, StructuredDataNode or an UnstructuredDataNode.
1446
1447 The properties of the new Node can be set by adding Properties to the template. Attempting to set a Property that the service considers to be 'readOnly' SHALL cause a PermissionDenied fault. The accepts and provides lists of Views for the Node cannot be set using this method.
1448
1449 The capabilities list for the Node cannot be set using this method.
1450
1451 \paragraph{Response}
1452 \subparagraph{Status code} A HTTP 201 status code
1453 \subparagraph{Body}
1454 A node representation including:
1455 \begin{itemize}
1456 \item \emph{node}: details of the new Node
1457 \end{itemize}
1458
1459 The \emph{accepts} list of Views for the Node SHALL be filled in by the service based on service capabilities.
1460
1461 The \emph{provides} list of Views for the Node MAY not be filled in until some data has been imported into the Node.
1462
1463 The \emph{capabilities} list for the Node MAY not be filled in until some data has been imported into the Node.
1464
1465 \paragraph{Faults}
1466 \begin{itemize}
1467 \item The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity body if the operation fails
1468 \item The service SHALL throw a HTTP 409 status code including a DuplicateNode fault in the entity body if a Node already exists with the same URI
1469 \item The service SHALL throw a HTTP 400 status code including an InvalidURI fault in the entity body if the requested URI is invalid
1470 \item If the URI node path does not match the node path of the HTTP PUT request the service must throw a HTTP 400 status including an InvalidURI fault in the entity body.
1471 \item The service SHALL throw a HTTP 400 status code including a TypeNotSupported fault in the entity body if the type specified in xs:type is not supported
1472 \item The service SHALL throw a HTTP 403 status code including PermissionDenied fault in the entity body if the user does not have permissions to perform the operation
1473 \item If a parent node in the URI path does not exist then the service SHALL throw a HTTP 404 status code including a ContainerNotFound fault in the entity body.
1474 \begin{itemize}
1475 \item For example, given the URI path /a/b/c, the service must throw a HTTP 404 status code including a ContainerNotFound fault in the entity body if either /a or /a/b do not exist.
1476 \end{itemize}
1477 \item If a parent node in the URI path is a LinkNode, the service SHALL throw a HTTP 400 status code including a LinkFound fault in the entity body.
1478 \begin{itemize}
1479 \item For example, given the URI path /a/b/c, the service must throw a HTTP 400 status code including a LinkFound fault in the entity body if either /a or /a/b are LinkNodes.
1480 \end{itemize}
1481 \end{itemize}
1482
1483 \paragraph{Example}
1484 Create a node
1485 \\[5px]
1486 \noindent
1487 The node to be created (newNode.xml):
1488 \begin{lstlisting}
1489 <vos:node xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
1490 xmlns="http://www.ivoa.net/xml/VOSpace/v2.1" xs:type="vos:UnstructuredDataNode" uri="vos://example.com!vospace/mydata1">
1491 <vos:properties>
1492 <vos:property uri="ivo://ivoa.net/vospace/core#description">My important results</vos:property>
1493 </vos:properties>
1494 <vos:accepts/>
1495 <vos:provides/>
1496 <vos:capabilities/>
1497 </vos:node>
1498 \end{lstlisting}
1499 Request:
1500 \begin{lstlisting}
1501 > curl -v -X PUT -d @newNode.xml -H "Content-type: text/xml" "http://server.example.com/vospace/nodes/mydata1"
1502 \end{lstlisting}
1503 Response:
1504 \begin{lstlisting}
1505 > PUT /vospace/nodes/mydata1 HTTP/1.1
1506 > Content-Type: text/xml
1507 >
1508 < HTTP/1.1 200 OK
1509 < Content-Type: text/xml
1510 <
1511 <vos:node xmlns:xi="http://www.w3.org/2001/XMLSchema-instance"
1512 xmlns="http://www.ivoa.net/xml/VOSpace/v2.1"
1513 xs:type="vos:UnstructuredDataNode"
1514 uri="vos://example.com!vospace/mydata1">
1515 <vos:properties>
1516 <vos:property uri="ivo://ivoa.net/vospace/core#description">My important results</vos:property>
1517 <vos:property uri="ivo://ivoa.net/vospace/core#date" readOnly="true">2015-05-22T23:06:32.966</vos:property>
1518 </vos:properties>
1519 <vos:accepts>
1520 <vos:view uri="ivo://ivoa.net/vospace/core#anyview"/>
1521 </vos:accepts>
1522 <vos:provides/>
1523 <vos:capabilities/>
1524 </vos:node>
1525 \end{lstlisting}
1526
1527 \subsubsection{moveNode}
1528 \label{subsubsec:movenode}
1529 Move a node within a VOSpace service.
1530
1531 Note that this does not cover moving data between two separate VOSpace services.
1532
1533 Moving nodes between separate VOSpace services SHOULD be handled by the client, using the import, export and delete methods.
1534
1535 When the source is a ContainerNode, all its children (the contents of the container) SHALL also be moved to the new destination.
1536
1537 When the destination is an existing ContainerNode, the source SHALL be placed under it (i.e. within the container).
1538
1539 The Node type cannot be changed using this method.
1540
1541 \paragraph{Request}
1542 \begin{itemize}
1543 \item A HTTP POST of a Job representation for the transfer (see section 3.6) to http://rest-endpoint/transfers.
1544 \end{itemize}
1545
1546 .auto is a reserved URI to indicate an autogenerated URI for the destination, i.e. vos://service/path/.auto SHOULD cause a new unique URI for the node within vos://service/path to be generated.
1547
1548 \paragraph{Response}
1549 \subparagraph{Status code} The initial response is a HTTP 303 status code with the Location header keyword assigned to the created job.
1550 \subparagraph{Body}
1551 If an autogenerated URI for the destination was specified in the request then its value SHALL be specified as a result in the Results List for the completed transfer with the id of ``destination'':
1552 \begin{lstlisting}
1553 <uws:job>
1554 ...
1555 <uws:jobInfo>
1556 <vos:direction>vos://example.com!vospace/mjg/.auto</vos:direction>
1557 ...
1558 <uws:results>
1559 <uws:result id="destination">vos://example.com!vospace/mjg/abc123</uws:result>
1560 </uws:results>
1561 ...
1562 </uws:job>
1563 \end{lstlisting}
1564
1565 \paragraph{Faults}
1566
1567 For all faults, the service shall set the PHASE to ``ERROR'' in the Job representation. The <errorSummary> element in the Job representation shall be set to the appropriate value for the fault type and the appropriate fault representation (see section 5.5) provided at the error URI: http://rest-endpoint/transfers/(jobid)/error.
1568
1569 \vspace{3mm}
1570 \begin{tabular}{ p{5cm} l p{4cm} }
1571 \textbf{Fault description} & \textbf{errorSummary} & \textbf{Fault representation} \\
1572 \hline
1573 Operation fails & Internal Fault & InternalFault \\
1574 \hline
1575 User does not have permissions to perform the operation &Permission Denied & PermissionDenied \\
1576 \hline
1577 Source node does not exist & Node Not Found & NodeNotFound \\
1578 \hline
1579 Destination node already exists and it is not a ContainerNode & Duplicate Node & DuplicateNode \\
1580 \hline
1581 A specified URI is invalid & Invalid URI & InvalidURI \\
1582 \hline
1583 \end{tabular}
1584 \vspace{3mm}
1585
1586 \paragraph{Example}
1587 Move a node
1588 \\[5px]
1589 \noindent
1590 The Job to be submitted (moveJob.xml):
1591 \begin{lstlisting}
1592 <vos:transfer xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
1593 xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1" >
1594 <vos:target>vos://example.com!vospace/mydata1</vos:target>
1595 <vos:direction>vos://example.com!vospace/mydata2</vos:direction>
1596 <vos:keepBytes>false</vos:keepBytes>
1597 </vos:transfer>
1598 \end{lstlisting}
1599 Request:
1600 \begin{lstlisting}
1601 > curl -v -X POST -d @moveJob.xml -H "Content-type: text/xml" "http://server.example.com/vospace/transfers"
1602 \end{lstlisting}
1603 Response:
1604 \begin{lstlisting}
1605 > POST /vospace/transfers HTTP/1.1
1606 > Content-Type: text/xml
1607 >
1608 < HTTP/1.1 303 See Other
1609 < Location: http://server.example.com/vospace/transfers/glmldqf591feljub
1610 < Content-Type: text/plain
1611 <
1612 \end{lstlisting}
1613 Job information can be seen by following the redirect to:
1614 \begin{lstlisting}
1615 > curl -v "http://server.example.com/vospace/transfers/glmldqf591feljub"
1616 \end{lstlisting}
1617 Response:
1618 \begin{lstlisting}
1619 > GET /vospace/transfers/glmldqf591feljub HTTP/1.1
1620 >
1621 < HTTP/1.1 200 OK
1622 < Content-Type: text/xml
1623 <
1624 <?xml version="1.0" encoding="UTF-8"?>
1625 <uws:job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
1626 <uws:jobId>glmldqf591feljub</uws:jobId>
1627 <uws:ownerId xs:nill="true" />
1628 <uws:phase>PENDING</uws:phase>
1629 <uws:quote>2015-05-23T11:44:03.993</uws:quote>
1630 <uws:startTime xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" xs:nil="true" />
1631 <uws:endTime xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" xs:nil="true" />
1632 <uws:executionDuration>43200</uws:executionDuration>
1633 <uws:destruction>2015-05-29T23:44:03.993</uws:destruction>
1634 <uws:parameters />
1635 <uws:results />
1636 <uws:jobInfo>
1637 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
1638 <vos:target>vos://example.com!vospace/mydata1</vos:target>
1639 <vos:direction>vos://example.com!vospace/mydata2</vos:direction>
1640 <vos:keepBytes>false</vos:keepBytes>
1641 </vos:transfer>
1642 </uws:jobInfo>
1643 </uws:job>
1644 \end{lstlisting}
1645 Now start the UWS job:
1646 \begin{lstlisting}
1647 > curl -v -d "PHASE=RUN" "http://server.example.com/vospace/transfers/glmldqf591feljub/phase"
1648 \end{lstlisting}
1649 Response:
1650 \begin{lstlisting}
1651 > POST /vospace/transfers/glmldqf591feljub/phase HTTP/1.1
1652 > Content-Type: text/xml
1653 >
1654 < HTTP/1.1 303 See Other
1655 < Location: http://server.example.com/vospace/transfers/glmldqf591feljub
1656 < Content-Type: text/plain
1657 <
1658 \end{lstlisting}
1659 Follow the redirect to see the phase. The job will be either RUNNING, COMPLETED or ERROR.
1660 \begin{lstlisting}
1661 > curl -v http://server.example.com/vospace/transfers/glmldqf591feljub/phase
1662 \end{lstlisting}
1663 Response:
1664 \begin{lstlisting}
1665 > GET /vospace/transfers/glmldqf591feljub/phase HTTP/1.1
1666 >
1667 < HTTP/1.1 200 OK
1668 < Content-Type: text/plain;charset=UTF-8
1669 <
1670 COMPLETED
1671 \end{lstlisting}
1672 If the job is in phase RUNNING, the phase can be polled intermittently until it is COMPLETED or ERROR.
1673 Error and result details can be seen by performing an HTTP GET to the job URL:
1674 \begin{lstlisting}
1675 > curl -v "http://server.example.com/vospace/transfers/glmldqf591feljub"
1676 \end{lstlisting}
1677
1678 \subsubsection{copyNode}
1679 \label{subsubsec:copynode}
1680 Copy a node with a VOSpace service.
1681 Note that this does not cover copying data between two separate VOSpace services.
1682 Copying nodes between separate VOSpace services SHOULD be handled by the client, using the import and export methods.
1683 When the source is a ContainerNode, all its children (the full contents of the container) SHALL get copied, i.e. this is a deep recursive copy.
1684 When the destination is an existing ContainerNode, the copy SHALL be placed under it (i.e. within the container).
1685 The Node type cannot be changed using this method.
1686
1687 \paragraph{Request}
1688 A HTTP POST of a Job representation for the transfer (see section \ref{subsec:transfers}) to http://rest-endpoint/transfers.
1689 .auto is the reserved URI to indicate an auto-generated URI for the destination, i.e. vos://service/path/.auto SHOULD cause a new unique URI for the node within vos://service/path to be generated.
1690
1691 \paragraph{Response}
1692 The initial response is a HTTP 303 status code with the Location header keyword assigned to the created job.
1693 If an autogenerated URI for the destination was specified in the request then its value SHALL be specified as a result in the Results List for the completed transfer with the id of "destination":
1694
1695 \begin{lstlisting}
1696 <uws:job>
1697 ...
1698 <uws:jobInfo>
1699 <vos:direction>vos://nvo.caltech!vospace/mjg/.auto</vos:direction>
1700 ...
1701 <uws:results>
1702 <uws:result id="destination">vos://nvo.caltech!vospace/mjg/abc123</uws:result>
1703 </uws:results>
1704 ...
1705 </uws:job>
1706 \end{lstlisting}
1707
1708 \paragraph{Faults}
1709 For all faults, the service shall set the PHASE to "ERROR" in the Job representation. The <errorSummary> element in the Job representation shall be set to the appropriate value for the fault type and the appropriate fault representation (see section \ref{subsec:fault arguments}) provided at the error URI: http://rest-endpoint/transfers/(jobid)/error.
1710
1711 \vspace{3mm}
1712 \begin{tabular}{ p{5cm} l p{4cm} }
1713 \textbf{Fault description} & \textbf{errorSummary} & \textbf{Fault representation} \\
1714 \hline
1715 Operation fails & Internal Fault & InternalFault \\
1716 \hline
1717 User does not have permissions to perform the operation & Permission Denied & PermissionDenied \\
1718 \hline
1719 Source node does not exist & Node Not Found & NodeNotFound \\
1720 \hline
1721 Destination node already exists and it is not a ContainerNode & Duplicate Node & DuplicateNode \\
1722 \hline
1723 A specified URI is invalid & Invalid URI & InvalidURI \\
1724 \hline
1725 \end{tabular}
1726 \vspace{3mm}
1727
1728 \paragraph{Example}
1729 Copy a VOSpace node
1730 \\[5px]
1731 \noindent
1732 The Job to be submitted (copyJob.xml):
1733 \begin{lstlisting}
1734 <vos:transfer xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
1735 xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1" >
1736 <vos:target>vos://example.com!vospace/mydata1</vos:target>
1737 <vos:direction>vos://example.com!vospace/mydir/.auto</vos:direction>
1738 <vos:keepBytes>true</vos:keepBytes>
1739 </vos:transfer>
1740 \end{lstlisting}
1741 Request:
1742 \begin{lstlisting}
1743 > curl -v -X POST -d @copyJob.xml -H "Content-type: text/xml" "http://server.example.come/vospace/transfers"
1744 \end{lstlisting}
1745 Response:
1746 \begin{lstlisting}
1747 > POST /vospace/transfers HTTP/1.1
1748 > Content-Type: text/xml
1749 >
1750 < HTTP/1.1 303 See Other
1751 < Location: http://server.example.com/vospace/transfers/usil5s8mdbgjwzvq
1752 < Content-Type: text/plain
1753 <
1754 * Closing connection #0
1755 \end{lstlisting}
1756 Job information can be seen by following the redirect to:
1757 \begin{lstlisting}
1758 > curl -v "http://server.example.com/vospace/transfers/usil5s8mdbgjwzvq"
1759 \end{lstlisting}
1760 Response:
1761 \begin{lstlisting}
1762 > GET /vospace/transfers/usil5s8mdbgjwzvq HTTP/1.1
1763 >
1764 < HTTP/1.1 200 OK
1765 < Content-Type: text/xml
1766 <
1767 <?xml version="1.0" encoding="UTF-8"?>
1768 <uws:job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
1769 <uws:jobId>usil5s8mdbgjwzvq</uws:jobId>
1770 <uws:ownerId xs:nill="true" />
1771 <uws:phase>PENDING</uws:phase>
1772 <uws:quote>2015-05-23T11:44:03.993</uws:quote>
1773 <uws:startTime xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" xs:nil="true" />
1774 <uws:endTime xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" xs:nil="true" />
1775 <uws:executionDuration>43200</uws:executionDuration>
1776 <uws:destruction>2015-05-29T23:44:03.993</uws:destruction>
1777 <uws:parameters />
1778 <uws:results>
1779 <uws:result id="destination" xlink:href="vos://example.com!vospace/mydir/ef9ce281f5bd4bff92c8991580cddff4"/>
1780 </uws:results>
1781 <uws:jobInfo>
1782 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
1783 <vos:target>vos://example.com!vospace/mydata1</vos:target>
1784 <vos:direction>vos://example.com!vospace/mydir/.auto</vos:direction>
1785 <vos:keepBytes>true</vos:keepBytes>
1786 </vos:transfer>
1787 </uws:jobInfo>
1788 </uws:job>
1789 \end{lstlisting}
1790 Now start the UWS job:
1791 \begin{lstlisting}
1792 > curl -v -d "PHASE=RUN" "http://server.example.com/vospace/transfers/usil5s8mdbgjwzvq/phase"
1793 \end{lstlisting}
1794 Response:
1795 \begin{lstlisting}
1796 > POST /vospace/transfers/usil5s8mdbgjwzvq/phase HTTP/1.1
1797 > Content-Type: text/xml
1798 >
1799 < HTTP/1.1 303 See Other
1800 < Location: http://server.example.com/vospace/transfers/usil5s8mdbgjwzvq
1801 < Content-Type: text/plain
1802 <
1803 \end{lstlisting}
1804 Follow the redirect to see the phase. The job will be either RUNNING, COMPLETED or ERROR.
1805 \begin{lstlisting}
1806 > curl -v http://server.example.com/vospace/transfers/usil5s8mdbgjwzvq/phase
1807 \end{lstlisting}
1808 Response:
1809 \begin{lstlisting}
1810 > GET /vospace/transfers/usil5s8mdbgjwzvq/phase HTTP/1.1
1811 >
1812 < HTTP/1.1 200 OK
1813 < Content-Type: text/plain;charset=UTF-8
1814 <
1815 COMPLETED
1816 \end{lstlisting}
1817 If the job is in phase RUNNING, the phase can be polled intermittently until it is COMPLETED or ERROR.
1818 Error and result details can be seen by performing an HTTP GET to the job URL:
1819 \begin{lstlisting}
1820 > curl -v "http://server.example.com/vospace/transfers/usil5s8mdbgjwzvq"
1821 \end{lstlisting}
1822
1823 \subsubsection{deleteNode}
1824 \label{subsubsec:deletenode}
1825 Delete a node.
1826 When the target is a ContainerNode, all its children (the contents of the container) SHALL also be deleted.
1827 Note that the same operation can also be achieved with a moveNode (see \ref{subsubsec:movenode}) with a .null node as the direction (destination node).
1828
1829 \paragraph{Request}
1830 A HTTP DELETE to the URL of an existing node
1831
1832 \paragraph{Response}
1833 A HTTP 204 status code
1834
1835 \paragraph{Faults}
1836 \begin{itemize}
1837 \item The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity-body if the operation fails
1838 \item The service SHALL throw a HTTP 403 status code including a PermissionDenied fault in the entity-body if the user does not have permissions to perform the operation
1839 \item The service SHALL throw a HTTP 404 status code including a NodeNotFound fault in the entity-body if the target node does not exist
1840 \item If a parent node in the URI path does not exist then the service SHALL throw a HTTP 404 status code including a ContainerNotFound fault in the entity-body
1841 \begin{itemize}
1842 \item For example, given the URI path /a/b/c, the service must throw a HTTP 404 status code including a ContainerNotFound fault in the entity-body if either /a or /a/b do not exist.
1843 \end{itemize}
1844 \item If a parent node in the URI path is a LinkNode, the service SHALL throw a HTTP 400 status code including a LinkFound fault in the entity-body.
1845 \begin{itemize}
1846 \item For example, given the URI path /a/b/c, the service must throw a HTTP 400 status code including a LinkFound fault in the entity-body if either /a or /a/b are LinkNodes.
1847 \end{itemize}
1848 \item If the target node in the URI path does not exist, the service SHALL throw a HTTP 404 status code including a NodeNotFound fault in the entity-body.
1849 \begin{itemize}
1850 \item For example, given the URI path /a/b/c, the service must throw a HTTP 404 status code including a NodeNotFound fault in the entity-body if /a/b/c does not exist.
1851 \end{itemize}
1852 \end{itemize}
1853
1854 \paragraph{Example}
1855 Delete a VOSpace node
1856 \\[5px]
1857 \noindent
1858 Request:
1859 \begin{lstlisting}
1860 > curl -v -X DELETE "http://server.example.com/vospace/nodes/mydata1"
1861 \end{lstlisting}
1862 Response:
1863 \begin{lstlisting}
1864 > DELETE /vospace/nodes/mydata1 HTTP/1.1
1865 >
1866 < HTTP/1.1 200 OK
1867 < Content-Type: text/plain
1868 <
1869 \end{lstlisting}
1870
1871 \subsection{Accessing metadata}
1872 \label{subsec:accessing metadata}
1873
1874 \subsubsection{getNode}
1875 \label{subsubsec:getnode}
1876 Get the details for a specific Node.
1877
1878 \paragraph{Request}
1879 A HTTP GET to the URL of an existing node http://rest-endpoint/nodes/path
1880 This can take the optional parameters to control the size of the response:
1881
1882 \begin{itemize}
1883 \item \emph{detail} with values of:
1884 \begin{itemize}
1885 \item \emph{min}: the returned record for the node contains minimum detail with all optional parts removed - the node type should be returned
1886 \begin{itemize}
1887 \item e.g. <Node uri="vos://service/name" xs:type="Node"/>
1888 \end{itemize}
1889 \item \emph{max}: the returned record for the node contains the maximum detail, including any xs:type specific extensions
1890 \item \emph{properties}: the returned record for the node contains the basic node element with a list of properties but no xs:type specific extensions
1891 \end{itemize}
1892 \item \emph{uri} with a value of a VOSpace identifier, URI-encoded according to RFC2396
1893 \item \emph{limit} with an integer value indicating the maximum number of results in the response.
1894 \begin{itemize}
1895 \item No limit indicates a request for an unpaged list. However the server MAY still impose its own limit on the size of an individual response, splitting the results into more than one page if required
1896 \end{itemize}
1897 \end{itemize}
1898 The list of supported protocols for a node can be retrieved with:
1899
1900 \begin{itemize}
1901 \item A HTTP POST of an empty protocol representation to the URL of an existing node http://rest-endpoint/nodes/path
1902 \end{itemize}
1903
1904 \paragraph{Response}
1905 A HTTP 200 status code and a Node representation in the entity-body
1906 When no parameters are present in the request, the full expanded record for the node SHALL be returned, including any xs:type specific extensions; otherwise the appropriate form for the specified value of the "detail" parameter SHALL be returned.
1907
1908 When the node is a container, the returned record will also contain a list of direct children nodes in the container (as <node> subelements under the < nodes> element).
1909
1910 If a ``uri'' and ``offset'' are specified in the request then the returned list will consist of the subset of children which begins at the node matching the specified value of the ``uri'' parameter and with cardinality matching the specified value of the ``offset'' parameter drawn from an ordered sequence of all children. The ordering is determined by the server but results must always be drawn from the same ordered sequence.
1911
1912 For the target node and for any children returned for a container node, the attribute \emph{xs:type} SHALL be included in the resulting Node document.
1913
1914 \paragraph{Faults}
1915 \begin{itemize}
1916 \item The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity-body if the operation fails
1917 \item The service SHALL throw a HTTP 403 status code including a PermissionDenied fault in the entity-body if the user does not have permissions to perform the operation
1918 \item The service SHALL throw a HTTP 404 status code including a NodeNotFound fault in the entity-body if the target Node does not exist
1919 \end{itemize}
1920
1921 \paragraph{Example}
1922 Get a VOSpace node
1923 \\[5px]
1924 \noindent
1925 Request:
1926 \begin{lstlisting}
1927 > curl -v "http://server.example.com/vospace/nodes/mydir?detail=min&uri=vos://example.com!vospace/mydir/file3401"
1928 \end{lstlisting}
1929 Response:
1930 \begin{lstlisting}
1931 > GET /vospace/nodes/mydir?detail=min&uri=vos://example.com!vospace/mydir/file3401 HTTP/1.1
1932 >
1933 < HTTP/1.1 200 OK
1934 < Content-Type: text/xml
1935 <
1936 <?xml version="1.0" encoding="UTF-8"?>
1937 <vos:node xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1" xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" uri="vos://example.com!vospace/mydir" xs:type="vos:ContainerNode">
1938 <vos:properties>
1939 <vos:property uri="ivo://ivoa.net/vospace/core#description">My award winning images</property>
1940 </vos:properties>
1941 <vos:accepts>
1942 <vos:view uri="ivo://ivoa.net/vospace/core#anyview"/>
1943 </vos:accepts>
1944 <vos:provides>
1945 <vos:view uri="ivo://ivoa/net/vospace/core#defaultview"/>
1946 </vos:provides>
1947 <vos:capabilities/>
1948 <vos:nodes>
1949 <vos:node uri="vos://example.com!vospace/mydir/file3401" xs:type="vos:DataNode"/>
1950 <vos:node uri="vos://example.com!vospace/mydir/file3406" xs:type="vos:DataNode"/>
1951 <vos:node uri="vos://example.com!vospace/mydir/file3532" xs:type="vos:DataNode"/>
1952 </vos:nodes>
1953 \end{lstlisting}
1954
1955 \subsubsection{setNode}
1956 \label{subsubsec:setnode}
1957 Set the property values for a specific Node
1958
1959 \paragraph{Request}
1960 A HTTP POST of a Node representation to the URL of an existing node http://rest-endpoint/nodes/path including:
1961 \begin{itemize}
1962 \item \emph{node}: A Node containing the Node uri and a list of the Properties to set (as defined in section 3.1)
1963 \end{itemize}
1964 This will add or update the node properties including any xs:type specific elements.
1965
1966 The operation is the union of existing values and new ones. An empty value sets the value to blank. To delete a Property, set the xs:nil attribute to true
1967
1968 This method cannot be used to modify the Node type.
1969
1970 This method cannot be used to modify the accepts or provides list of Views for the Node.
1971
1972 This method cannot be used to create children of a container Node.
1973
1974 \paragraph{Response}
1975 A HTTP 200 status code and a Node representation in the entity-body
1976 The full expanded record for the node SHALL be returned, including any xs:type specific extensions.
1977
1978 \paragraph{Faults}
1979 \begin{itemize}
1980 \item The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity-body if the operation fails
1981 \item The service SHALL throw a HTTP 403 status code including a PermissionDenied fault in the entity-body if the request attempts to modify a read-only Property
1982 \item The service SHALL throw a HTTP 403 status code including a PermissionDenied fault in the entity-body if the user does not have permissions to perform the operation
1983 \item The service SHALL throw a HTTP 404 status code including a NodeNotFound fault in the entity-body if the target Node does not exist
1984 \item If a parent node in the URI path does not exist then the service SHALL throw a HTTP 404 status code including a ContainerNotFound fault in the entity-body
1985 \begin{itemize}
1986 \item For example, given the URI path /a/b/c, the service must throw a HTTP 404 status code including a ContainerNotFound fault in the entity-body if either /a or /a/b do not exist.
1987 \end{itemize}
1988 \item The service SHALL throw a HTTP 400 status code including an InvalidArgument fault in the entity-body if a specified property value is invalid
1989 \end{itemize}
1990
1991 \paragraph{Example}
1992 Set node metadata
1993 \\[5px]
1994 \noindent
1995 The updated node (setNode.xml) is:
1996 \begin{lstlisting}
1997 <node xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" xs:type="vos:UnstructuredDataNode" xmlns="http://www.ivoa.net/xml/VOSpace/v2.1" uri="vos://nvo.caltech!vospace/mydata1">
1998 <properties>
1999 <property uri="ivo://ivoa.net/vospace/core#title" readOnly="false">Title for my data</property>
2000 </properties>
2001 <accepts/>
2002 <provides/>
2003 <capabilities/>
2004 </node>
2005 \end{lstlisting}
2006 Request:
2007 \begin{lstlisting}
2008 > curl -v -X POST -d @setNode.xml -H "Content-type: text/xml" "http://server.example.com/vospace/nodes/mydata1"
2009 \end{lstlisting}
2010 Response:
2011 \begin{lstlisting}0)
2012 > POST /vospace/nodes/mydata1 HTTP/1.1
2013 > Content-type: text/xml
2014 >
2015 < HTTP/1.1 200 OK
2016 < Content-Type: text/xml
2017 <
2018 <?xml version="1.0" encoding="UTF-8"?>
2019 <vos:node xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1" xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" uri="vos://cadc.nrc.ca!vospace/mydata1" xs:type="vos:DataNode" busy="false">
2020 <vos:properties>
2021 <vos:property uri="ivo://ivoa.net/vospace/core#length" readOnly="true">44</vos:property>
2022 <vos:property uri="ivo://ivoa.net/vospace/core#MD5" readOnly="true">12c13e49f2fd37e2c91bcca6acb78a08</vos:property>
2023 <vos:property uri="ivo://ivoa.net/vospace/core#date" readOnly="true">2015-05-24T23:02:10.397</vos:property>
2024 <vos:property uri="ivo://ivoa.net/vospace/core#title" readOnly="false">Title for my data</vos:property>
2025 </vos:properties>
2026 <vos:accepts>
2027 <vos:view uri="ivo://ivoa.net/vospace/core#anyview"/>
2028 </vos:accepts>
2029 <vos:provides />
2030 </vos:node>
2031 \end{lstlisting}
2032
2033 % \subsubsection{findNodes}
2034 % \label{subsubsec:findnodes}
2035 % Find nodes whose properties match the specified values.
2036 %
2037 % This operation is OPTIONAL.
2038 %
2039 % \paragraph{Request}
2040 % A HTTP POST of a Job representation of a Search (see section 3.7) to http://rest-endpoint/searches
2041 % A null value of the "matches" parameter implies a full listing of the space.
2042 %
2043 % \paragraph{Response}
2044 % The initial response is a HTTP 303 status code with the Location header keyword assigned to the created job.
2045 %
2046 % The search results representation can be retrieved directly from the link reported in the Results List, available from the results endpoint - http://rest-endpoint/searches/(jobid)/results -, the standard UWS location under the results endpoint - http://rest-endpoint/searches/(jobid)/results/searchDetails - (which may well just be a redirect to the former link), or as part of the full Job representation from http://rest-endpoint/searches/(jobid). The result element in the Results List SHALL have an id of "searchDetails":
2047 %
2048 % \begin{lstlisting}
2049 % <uws:job>
2050 % ...
2051 % <uws:results>
2052 % <uws:result id="searchDetails" xlink:href="http://rest-endpoint/searches/(jobid)/results/listing1"/>
2053 % </uws:results>
2054 % ...
2055 % </uws:job>
2056 % \end{lstlisting}
2057 %
2058 % \paragraph{Faults}
2059 % For all faults, the service shall set the PHASE to ``ERROR'' in the Job representation. The <errorSummary> element in the Job representation shall be set to the appropriate value for the fault type and the appropriate fault representation (see section 5.5) provided at the error URI: http://rest-endpoint/transfers/(jobid)/error.
2060 %
2061 % \vspace{3mm}
2062 % \begin{tabular}{ p{5cm} l p{4cm} }
2063 % \textbf{Fault description} & \textbf{errorSummary} & \textbf{Fault representation} \\
2064 % \hline
2065 % Operation not supported & Operation Not Supported & OperationNotSupported \\
2066 % \hline
2067 % Operation fails & Internal Fault & InternalFault \\
2068 % \hline
2069 % User does not have permissions to perform the operation & Permission Denied & PermissionDenied \\
2070 % \hline
2071 % A particular property is specified and does not exist in the space & Property Not Found & PropertyNotFound \\
2072 % \hline
2073 % \end{tabular}
2074 % \vspace{3mm}
2075 %
2076 % \paragraph{Example}
2077 %
2078 %
2079 % Find VOSpace nodes
2080 % \\[5px]
2081 % \noindent
2082 % The Job to be submitted (searchJob.xml) is:
2083 % \begin{lstlisting}
2084 % <vos:search xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
2085 % <vos:detail>properties</vos:detail>
2086 % <vos:matches>ivo://ivoa.net/vospace/core#description='galax'</vos:matches>
2087 % <vos:search>
2088 % \end{lstlisting}
2089 % Request:
2090 % \begin{lstlisting}
2091 % > curl -v -X POST -d @searchJob.xml -H "Content-type: text/xml" "http://localhost:8000/searches"
2092 % \end{lstlisting}
2093 % Response:
2094 % \begin{lstlisting}
2095 % > POST /searches HTTP/1.1
2096 % > Content-Type: text/xml
2097 % >
2098 % < HTTP/1.1 303 See Other
2099 % < Location: http://localhost:8080/searches/8c5b0f78cd5a44af8694f10da1b92060
2100 % < Content-Type: text/html
2101 % <
2102 % \end{lstlisting}
2103 % This resource can be found at:
2104 % \begin{lstlisting}
2105 % http://localhost:8080/searches/8c5b0f78cd5a44af8694f10da1b92060
2106 % \end{lstlisting}
2107 % The status of the job can now be polled at the job location:
2108 % \begin{lstlisting}
2109 % > curl -v "http://localhost:8000/searches/8c6e7bc53ee848638cda35817e47da65"
2110 % \end{lstlisting}
2111 % Response:
2112 % \begin{lstlisting}
2113 % > GET /searches/8c6e7bc53ee848638cda35817e47da65 HTTP/1.1
2114 % >
2115 % < HTTP/1.1 200 OK
2116 % < Content-Type: text/xml
2117 % <
2118 % <uws:job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" xmlns:xlink="http://www.w3.org/1999/xlink"
2119 % xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" xs:schemaLocation="http://www.ivoa.net/xml/UWS/v1.0 UWS.xsd ">
2120 % <uws:jobId>8c6e7bc53ee848638cda35817e47da65<
2121 % <uws:ownerId xs:nil="true"/>
2122 % <uws:phase>COMPLETED</uws:phase>
2123 % <uws:startTime>2010-03-12T19:50:56.552278</uws:startTime>
2124 % <uws:endTime>2010-03-12T19:50:56.562416</uws:endTime>
2125 % <uws:executionDuration>0</uws:executionDuration>
2126 % <uws:destruction xs:nil="true"/>
2127 % <uws:jobInfo>
2128 % <vos:search>
2129 % <vos:detail>properties</vos:detail>
2130 % <vos:matches>ivo://ivoa.net/vospace/core#description='galax'</vos:matches>
2131 % <vos:search>
2132 % <uws:jobInfo>
2133 % <uws:results>
2134 % <uws:result id="searchDetails" xlink:href="http://localhost:8000/searches/d55814f88d974c21afe5ad50e4e875c8/results/listing1"/>
2135 % </uws:results>
2136 % </uws:job>
2137 % \end{lstlisting}
2138 % Once the Job has completed, the result can be obtained from the URL reported in the result element:
2139 % \begin{lstlisting}
2140 % > curl -v "http://localhost:8000/searches/d55814f88d974c21afe5ad50e4e875c8/results/listing1"
2141 % \end{lstlisting}
2142 % Response:
2143 % \begin{lstlisting}
2144 % > GET /searches/d55814f88d974c21afe5ad50e4e875c8/results/listing1 HTTP/1.1
2145 % >
2146 % < HTTP/1.1 200 OK
2147 % < Content-Type: text/html
2148 % <
2149 % <nodes xmlns="http://www.ivoa.net/xml/VOSpace/v2.1"
2150 % xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
2151 % <node uri="vos://nvo.caltech!vospace/mydir/img1" xs:type="vos:UnstructuredDataNode">
2152 % <properties>
2153 % <property uri="ivo://ivoa.net/vospace/core#description">This is an R-band image of the galaxy NGC 3276</property>
2154 % </properties>
2155 % </node>
2156 % <node uri="vos://nvo.caltech!vospace/mydir/img5" xs:type="vos:StructuredDataNode">
2157 % <properties>
2158 % <property uri="ivo://ivoa.net/vospace/core#description">This is a Chandra mosaic of the Fornax cluster of galaxies</property>
2159 % </properties>
2160 % </node>
2161 % </nodes>
2162 % \end{lstlisting}
2163
2164 \subsection{Transferring data}
2165 \label{subsec:transferringdata}
2166 Two modes are supported for external data transfers: a simple HTTP GET to retrieve data from a service (pullFromVoSpace) and a more general mechanism which employs a UWS-based approach [UWS] for submitting general data transfer requests (see section \ref{subsec:transfers}). In the latter, four directions are specified in which external data transfers can happen:
2167 \begin{itemize}
2168 \item sending data to a service (pushToVoSpace)
2169 \item importing data into a service (pullToVoSpace)
2170 \item reading data from a service (pullFromVoSpace)
2171 \item sending data from a service (pushFromVoSpace)
2172 \end{itemize}
2173
2174 A transfer job is created by a HTTP POST of an appropriate Job representation to the transfers endpoint of the service: http://rest-endpoint/transfers. The following example shows a transfer document for a pushToVoSpace operation:
2175
2176 \begin{lstlisting}
2177 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
2178 <vos:target>vos://server.example.com!vospace/mydata1</vos:target>
2179 <vos:direction>pushToVoSpace</vos:direction>
2180 <vos:view uri="ivo://net.ivoa/vospace/core#fits"/>
2181 <vos:protocol uri="ivo://net.ivoa/vospace/core#httpsput">
2182 <vos:securityMethod uri="ivo://ivoa.net/sso#tls-with-certificate"/>
2183 </vos:protocol>
2184 </vos:transfer>
2185 \end{lstlisting}
2186
2187 This example transfer job is making a request for an TLS endpoint that supports client certificates that is to be used for performing an HTTP PUT of a file.
2188
2189 The service returns the UWS jobid of the transfer and it can then be initiated with a HTTP POST of the single parameter ``PHASE=RUN'' to the appropriate job endpoint: http://rest-endpoint/transfers/(jobid)/phase. Alternatively the transfer can also be run immediately on creation by adding a ``PHASE=RUN'' to the initial Job representation.
2190
2191 The status of any transfer can be obtained by polling the phase endpoint for a particular transfer, i.e. a HTTP GET to http://rest-endpoint/transfers/(jobid)/phase.
2192
2193 Once a transfer has completed, any results can be obtained by following the link in the Results List available from the results endpoint for that transfer, i.e. with a HTTP GET to http://rest-endpoint/transfers/(jobid)/results. This pertains particularly to the transfer methods in which data is sent to or read from a service-negotiated URL (pushToVoSpace and pullFromVoSpace).
2194
2195 A transfer can also be aborted at any stage with a HTTP POST of the parameter ``PHASE=ABORT'' to the endpoint: http://rest-endpoint/transfers/(jobid)/phase
2196
2197 More specific details for each of the four directions are given in the sections following.
2198
2199 \subsubsection{pushToVoSpace}
2200 \label{subsubsec:pushtovospace}
2201 Request a list of URLs to send data to a VOSpace node.
2202
2203 This method asks the server for a list of one or more URLs that the client can use to send data to.
2204
2205 The data transfer is initiated by the client, after it has received the response from the VOSpace service.
2206
2207 The primary use case for this method is client that wants to send some data directly to a VOSpace service.
2208
2209 This operation is OPTIONAL.
2210
2211 \paragraph{Request}
2212 An HTTP POST of a Job representation for the transfer to http://rest-endpoint/transfers or http://rest-endpoint/synctrans
2213
2214 If a Node already exists at the target URI, then the data SHALL be imported into the existing Node and the Node properties SHALL be cleared unless the node is a ContainerNode.
2215
2216 If there is no Node at the target URI, then the service SHALL create a new Node using the uri and the default xs:type for the space.
2217
2218 The transfer representation contains details of the View and a list of the Protocols (and, optionally, the preferred security method(s) per protocol) that the client wants to use.
2219
2220 The list of Protocols SHOULD not contain endpoint addresses, the service will supply the endpoint addresses in the response.
2221
2222 The service SHALL ignore any of the requested protocols and security methods that it does not understand or is unable to support.
2223
2224 .auto is the reserved URI to indicate an auto-generated URI for the destination, i.e. vos://service/path/.auto SHOULD cause a new unique URI for the node within vos://service/path to be generated. If supported, this URI SHALL be specified as a result in the Results list for the completed transfer with the id of "target".
2225
2226 A pushToVoSpace transfer may be initiated with an HTTP POST of a Job representation of the transfer to http://rest-endpoint/transfers. The service SHALL respond with a redirect to the newly created job. (See Example 1)
2227
2228 A pushToVoSpace transfer may be initiated with an HTTP POST of a Job representation of the transfer to http://rest-endpoint/synctrans. The service SHALL respond with a redirect to the transfer details of the job. (See Example 2)
2229
2230 A pushToVoSpace transfer may be initiated with an HTTP POST or GET to http://rest-endpoint/synctrans with the following required URL query parameters:
2231 \begin{itemize}
2232 \item \emph{TARGET}: The value is the URI of the target node
2233 \begin{itemize}
2234 \item Example: vos://example.com$\mathtt{\sim}$vospace/mydata1
2235 \end{itemize}
2236 \item \emph{DIRECTION}: pushToVoSpace
2237 \item \emph{PROTOCOL}: The standard URI of the protocol to use (see section ~\ref{subsubsec:standard protocols})
2238 \begin{itemize}
2239 \item Example: ivo://ivoa.net/vospace/core\#httpput
2240 \end{itemize}
2241 \end{itemize}
2242
2243 The following optional parameters may also be included:
2244 \begin{itemize}
2245 \item \emph{VIEW}: The standard URI of the view to use
2246 \begin{itemize}
2247 \item Example: ivo://ivoa.net/vospace/core\#fits
2248 \end{itemize}
2249 \item \emph{SECURITYMETHOD}: The standard URI of the security method to use
2250 \begin{itemize}
2251 \item Example: ivo://ivoa.net/sso\#tls-with-certificate
2252 \end{itemize}
2253 \end{itemize}
2254
2255 The service SHALL respond with the job containing the transfer results in the response body. (See Example 3)
2256
2257 \paragraph{Response}
2258 Redirect responses are a HTTP 303 status code with the Location header keyword assigned to the created job.
2259 The service SHALL select which of the requested Protocols it is willing to provide and fill in the operational details for each one in the transfer result representation - this SHOULD normally include specifying the destination URL of the transfer protocol endpoint.
2260
2261 The transfer result SHOULD not include any Protocols or security methods that it is unable to support.
2262
2263 The transfer results representation can be retrieved directly from the link reported in the Results List, available either from the results endpoint - http://rest-endpoint/transfers/(jobid)/results - or as part of the full Job representation for the completed transfer available from http://rest-endpoint/transfers/(jobid). The result element in the Results List SHALL have an id of "transferDetails":
2264 \begin{lstlisting}
2265 <uws:job>
2266 ...
2267 <uws:results>
2268 <uws:result id="transferDetails" xlink:href="http://rest-endpoint/transfers/(jobid)/results/details1"/>
2269 </uws:results>
2270 ...
2271 </uws:job>
2272 \end{lstlisting}
2273 For synchronous job postings:
2274 \begin{itemize}
2275 \item A HTTP 303 status code with the Location header keyword assigned to the endpoint: http://rest-endpoint/transfers/(jobid)/results/transferDetails.
2276 \end{itemize}
2277 The HTTP 303 redirect points to a transfer representation with the required transfer details and endpoints.
2278
2279 For parameter based transfers, the transfer representation with the required transfer details and endpoints is returned directly in the response--no redirect is issued.
2280
2281 \paragraph{Faults}
2282 For all faults using the UWS mode, the service shall set the PHASE to "ERROR" in the Job representation. The <errorSummary> element in the Job representation shall be set to the appropriate value for the fault type and the appropriate fault representation (see section 5.5) provided at the error URI: http://rest-endpoint/transfers/(jobid)/error.
2283
2284 \vspace{3mm}
2285 \begin{tabular}{ p{5cm} l p{4cm} }
2286 \textbf{Fault description} & \textbf{errorSummary} & \textbf{Fault representation} \\
2287 \hline
2288 Operation not supported & Operation Not Supported & OperationNotSupported \\
2289 \hline
2290 Operation fails & Internal Fault & InternalFault \\
2291 \hline
2292 User does not have permissions to perform the operation & Permission Denied & PermissionDenied \\
2293 \hline
2294 Service does not support the requested View & View Not Supported & ViewNotSupported \\
2295 \hline
2296 Service supports none of the requested Protocols & Protocol Not Supported &ProtocolNotSupported \\
2297 \hline
2298 A View parameter is invalid & Invalid Argument & InvalidArgument \\
2299 \hline
2300 A Protocol parameter is invalid & Invalid Argument & InvalidArgument \\
2301 \hline
2302 \end{tabular}
2303 \vspace{3mm}
2304
2305 If an error occurs with the synchronous convenience mode, the resulting transfers document SHOULD have no protocols. The client can then retrieve the Job representation for error information as with asynchronous transfers.
2306
2307 \paragraph{Example 1}
2308 pushToVoSpace over the asynchronous endpoint
2309 \\[5px]
2310 \noindent
2311 The Job to be submitted (pushToVoSpace.xml):
2312 \begin{lstlisting}
2313 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
2314 <vos:target>vos://example.com!vospace/mydata1</vos:target>
2315 <vos:direction>pushToVoSpace</vos:direction>
2316 <vos:view uri="ivo://ivoa.net/vospace/core#fits"/>
2317 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpput" />
2318 <vos:param uri="ivo://ivoa.net/vospace/core#length">388943</vos:param>
2319 </vos:transfer>
2320 \end{lstlisting}
2321 Request:
2322 \begin{lstlisting}
2323 > curl -v -X POST -d @pushToVoSpace.xml -H "Content-type: text/xml" "http://server.example.com/vospace/transfers"
2324 \end{lstlisting}
2325 Response:
2326 \begin{lstlisting}
2327 > POST /vospace/transfers HTTP/1.1
2328 > Content-type: text/xml
2329 >
2330 < HTTP/1.1 303 See Other
2331 < Location: http://server.example.com/vospace/transfers/zkqzpftmufdi8luh
2332 < Content-Type: text/plain
2333 <
2334 \end{lstlisting}
2335 The PENDING job can be seen by following the redirect to:
2336 \begin{lstlisting}
2337 > curl -v http://server.example.com/vospace/transfers/zkqzpftmufdi8luh
2338 \end{lstlisting}
2339 Response:
2340 \begin{lstlisting}
2341 > GET /vospace/transfers/zkqzpftmufdi8luh HTTP/1.1
2342 >
2343 < HTTP/1.1 200 OK
2344 < Content-Type: text/xml
2345 <
2346 <?xml version="1.0" encoding="UTF-8"?>
2347 <uws:job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
2348 <uws:jobId>zkqzpftmufdi8luh</uws:jobId>
2349 <uws:phase>PENDING</uws:phase>
2350 <uws:quote>2015-05-26T11:06:45.713</uws:quote>
2351 <uws:startTime xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xs:nil="true" />
2352 <uws:endTime xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xs:nil="true" />
2353 <uws:executionDuration>43200</uws:executionDuration>
2354 <uws:destruction>2015-06-01T23:06:45.713</uws:destruction>
2355 <uws:parameters />
2356 <uws:results />
2357 <uws:jobInfo>
2358 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
2359 <vos:target>vos://example.com!vospace/mydata1</vos:target>
2360 <vos:direction>pushToVoSpace</vos:direction>
2361 <vos:view uri="ivo://ivoa.net/vospace/core#fits" />
2362 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpput" />
2363 </vos:transfer>
2364 </uws:jobInfo>
2365 </uws:job>
2366 \end{lstlisting}
2367 The job can now be started by posting PHASE=RUN:
2368 \begin{lstlisting}
2369 curl -v -X POST -d "PHASE=RUN" http://server.example.com/vospace/transfers/zkqzpftmufdi8luh/phase
2370 \end{lstlisting}
2371 Response:
2372 \begin{lstlisting}
2373 > POST /vospace/transfers/zkqzpftmufdi8luh/phase HTTP/1.1
2374 > Content-Type: text/xml
2375 >
2376 < HTTP/1.1 303 See Other
2377 < Location: http://server.examle.com/vospace/transfers/zkqzpftmufdi8luh
2378 < Content-Type: text/plain
2379 <
2380 \end{lstlisting}
2381 The EXECUTING job can be seen by following the redirect to:
2382 \begin{lstlisting}
2383 http://server.examle.com/vospace/transfers/zkqzpftmufdi8luh
2384 \end{lstlisting}
2385 Response:
2386 \begin{lstlisting}
2387 > GET /vospace/transfers/zkqzpftmufdi8luh HTTP/1.1
2388 >
2389 < HTTP/1.1 200 OK
2390 < Content-Type: text/xml
2391 <
2392 <?xml version="1.0" encoding="UTF-8"?>
2393 <uws:job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
2394 <uws:jobId>zkqzpftmufdi8luh</uws:jobId>
2395 <uws:phase>EXECUTING</uws:phase>
2396 <uws:quote>2015-05-26T11:06:45.713</uws:quote>
2397 <uws:startTime>2015-05-25T23:17:41.217</uws:startTime>
2398 <uws:endTime xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xs:nil="true" />
2399 <uws:executionDuration>43200</uws:executionDuration>
2400 <uws:destruction>2015-06-01T23:06:45.713</uws:destruction>
2401 <uws:parameters />
2402 <uws:results>
2403 <uws:result id="transferDetails" xlink:href="http://server.example.com/vospace/transfers/zkqzpftmufdi8luh/results/transferDetails" />
2404 <uws:result id="dataNode" xlink:href="vos://example.com!vospace/mydata1" />
2405 </uws:results>
2406 <uws:jobInfo>
2407 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
2408 <vos:target>vos://example.com!vospace/mydata1</vos:target>
2409 <vos:direction>pushToVoSpace</vos:direction>
2410 <vos:view uri="ivo://ivoa.net/vospace/core#fits" />
2411 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpput" />
2412 </vos:transfer>
2413 </uws:jobInfo>
2414 </uws:job>
2415 \end{lstlisting}
2416 The details of the transfer negotiation can be see by following the \emph{transferDetails} result:
2417 \begin{lstlisting}
2418 > curl -v http://server.example.com/vospace/transfers/zkqzpftmufdi8luh/results/transferDetails
2419 \end{lstlisting}
2420 Response:
2421 \begin{lstlisting}
2422 > GET /vospace/transfers/zkqzpftmufdi8luh/results/transferDetails HTTP/1.1
2423 >
2424 < HTTP/1.1 200 OK
2425 < Content-Type: text/xml;charset=UTF-8
2426 <
2427 <?xml version="1.0" encoding="UTF-8"?>
2428 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
2429 <vos:target>vos://example.com!vospace/mydata1</vos:target>
2430 <vos:direction>pushToVoSpace</vos:direction>
2431 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpput">
2432 <vos:endpoint>http://storage1.example.com/trans/mydata1</vos:endpoint>
2433 </vos:protocol>
2434 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpput">
2435 <vos:endpoint>http://storage2.example.com/mydata1</vos:endpoint>
2436 </vos:protocol>
2437 </vos:transfer>
2438 \end{lstlisting}
2439 The FITS file can now be pushed over HTTP PUT to one of the endpoints listed in the transfer details.
2440 \begin{lstlisting}
2441 > curl -v -T mydata1 "http://storage1.example.com/mydata1"
2442 \end{lstlisting}
2443 Response:
2444 \begin{lstlisting}
2445 > PUT /trans/mydata1 HTTP/1.1
2446 > Content-Type: text/xml
2447 >
2448 < HTTP/1.1 100 Continue
2449 < HTTP/1.1 200 OK
2450 < Content-Type: text/plain
2451 <
2452 \end{lstlisting}
2453 On successful file transfer completion the job will be COMPLETED:
2454 \begin{lstlisting}
2455 curl -v http://server.examle.com/vospace/transfers/zkqzpftmufdi8luh/phase
2456 \end{lstlisting}
2457 Response:
2458 \begin{lstlisting}
2459 > GET /vospace/transfers/zkqzpftmufdi8luh/phase HTTP/1.1
2460 >
2461 < HTTP/1.1 200 OK
2462 < Content-Type: text/plain;charset=UTF-8
2463 <
2464 COMPLETED
2465 \end{lstlisting}
2466
2467 \paragraph{Example 2}
2468 pushToVoSpace over the synchronous endpoint
2469 \\[5px]
2470 \noindent
2471 The Job to be submitted (pushToVoSpace.xml):
2472 \begin{lstlisting}
2473 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
2474 <vos:target>vos://example.com!vospace/mydata1</vos:target>
2475 <vos:direction>pushToVoSpace</vos:direction>
2476 <vos:view uri="ivo://ivoa.net/vospace/core#fits"/>
2477 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpput" />
2478 </vos:transfer>
2479 \end{lstlisting}
2480 Request:
2481 \begin{lstlisting}
2482 > curl -v -X POST -d @pushToVoSpace.xml -H "Content-type: text/xml" "http://server.example.com/vospace/synctrans"
2483 \end{lstlisting}
2484 Response:
2485 \begin{lstlisting}
2486 > POST /vospace/synctrans HTTP/1.1
2487 > Content-Type: text/xml
2488 >
2489 < HTTP/1.1 303 See Other
2490 < Location: http://server.example.com/vospace/transfers/zkqzpftmufdi8luh/results/transferDetails
2491 < Content-Type: text/plain
2492 <
2493 \end{lstlisting}
2494 The negotiated transfer details can be seen by following the redirect to:
2495 \begin{lstlisting}
2496 http://server.examlpe.com/vospace/transfers/zkqzpftmufdi8luh/results/transferDetails
2497 \end{lstlisting}
2498 Request:
2499 \begin{lstlisting}
2500 > curl -v http://server.example.com/vospace/transfers/zkqzpftmufdi8luh/results/transferDetails
2501 \end{lstlisting}
2502 Response:
2503 \begin{lstlisting}
2504 > GET /vospace/transfers/zkqzpftmufdi8luh/results/transferDetails HTTP/1.1
2505 >
2506 < HTTP/1.1 200 OK
2507 < Content-Type: text/xml;UTF-8
2508 <
2509 <?xml version="1.0" encoding="UTF-8"?>
2510 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
2511 <vos:target>vos://example.com!vospace/mydata1</vos:target>
2512 <vos:direction>pushToVoSpace</vos:direction>
2513 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpput">
2514 <vos:endpoint>http://storage1.example.com/trans/mydata1</vos:endpoint>
2515 </vos:protocol>
2516 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpput">
2517 <vos:endpoint>http://storage2.example.com/mydata1</vos:endpoint>
2518 </vos:protocol>
2519 </vos:transfer>
2520 \end{lstlisting}
2521
2522 \paragraph{Example 3}
2523 pushToVoSpace over the synchronous endpoint with securityMethod
2524 \\[5px]
2525 \noindent
2526 A transfer request for endpoints supporting basic authentication over HTTP or TLS with a client certificate over SSL.\\
2527 The Job to be submitted (pushToVoSpace.xml):
2528 \begin{lstlisting}
2529 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
2530 <vos:target>vos://example.com!vospace/mydata1</vos:target>
2531 <vos:direction>pushToVoSpace</vos:direction>
2532 <vos:view uri="ivo://ivoa.net/vospace/core#fits"/>
2533 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpsput">
2534 <vos:securityMethod uri="ivo://ivoa.net/sso#tls-with-certificate"/>
2535 </vos:protocol>
2536 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpput">
2537 <vos:securityMethod uri="uri="http://www.w3.org/Protocols/HTTP/1.0/spec/html#BasicAA"/>
2538 </vos:protocol>
2539 </vos:transfer>
2540 \end{lstlisting}
2541 Request:
2542 \begin{lstlisting}
2543 > curl -v -X POST -d @pushToVoSpace.xml -H "Content-type: text/xml" "http://server.example.com/vospace/synctrans"
2544 \end{lstlisting}
2545 Response:
2546 \begin{lstlisting}
2547 > POST /vospace/synctrans HTTP/1.1
2548 > Content-Type: text/xml
2549 >
2550 < HTTP/1.1 303 See Other
2551 < Location: http://server.example.com/vospace/transfers/zkqzpftmufdi8luh/results/transferDetails
2552 < Content-Type: text/plain
2553 <
2554 \end{lstlisting}
2555 The negotiated transfer details can be seen by following the redirect to:
2556 \begin{lstlisting}
2557 http://server.example.com/vospace/transfers/zkqzpftmufdi8luh/results/transferDetails
2558 \end{lstlisting}
2559 Request:
2560 \begin{lstlisting}
2561 > curl -v http://server.example.come/vospace/transfers/zkqzpftmufdi8luh/results/transferDetails
2562 \end{lstlisting}
2563 Response:
2564 \begin{lstlisting}
2565 > GET /vospace/transfers/zkqzpftmufdi8luh/results/transferDetails HTTP/1.1
2566 >
2567 < HTTP/1.1 200 OK
2568 < Content-Type: text/xml;charset=UTF-8
2569 <
2570 <?xml version="1.0" encoding="UTF-8"?>
2571 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
2572 <vos:target>vos://example.com!vospace/mydata1</vos:target>
2573 <vos:direction>pushToVoSpace</vos:direction>
2574 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpsput">
2575 <vos:endpoint>https://storage1.example.com/trans/mydata1</vos:endpoint>
2576 <vos:securityMethod uri="ivo://ivoa.net/sso#tls-with-certificate"/>
2577 </vos:protocol>
2578 </vos:transfer>
2579 \end{lstlisting}
2580 The service has replied with a single HTTPS endpoint that support TLS with client certificates.
2581
2582 \paragraph{Example 4}
2583 pushToVoSpace over the synchronous endpoint with URL parameters
2584 \\[5px]
2585 \noindent
2586 Request:
2587 \begin{lstlisting}
2588 curl -v -X POST "http://server.example.com/vospace/synctrans?TARGET=vos://example.com~vospace/mydata1&DIRECTION=pushToVoSpace&PROTOCOL=ivo://ivoa.net/vospace/core%23httpput"
2589 \end{lstlisting}
2590 (Note that the \# sign in PROTOCOL is URL encoded as \%23 and that the alternate separator `$\mathtt{\sim}$' is used instead of `!' in the TARGET) \\
2591 \\
2592 Response:
2593 \begin{lstlisting}
2594 > POST /vospace/synctrans?TARGET=vos://example.com~vospace/mydata1&DIRECTION=pushToVoSpace&PROTOCOL=ivo://ivoa.net/vospace/core\%23httpput HTTP/1.1
2595 >
2596 < HTTP/1.1 200 OK
2597 < Content-Type: text/xml;charset=UTF-8
2598 <
2599 <?xml version="1.0" encoding="UTF-8"?>
2600 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
2601 <vos:target>vos://example.com!vospace/mydata1</vos:target>
2602 <vos:direction>pushToVoSpace</vos:direction>
2603 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpput">
2604 <vos:endpoint>http://storage1.example.com/trans/mydata1</vos:endpoint>
2605 </vos:protocol>
2606 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpput">
2607 <vos:endpoint>http://storage2.example.com/mydata1</vos:endpoint>
2608 </vos:protocol>
2609 </vos:transfer>
2610 \end{lstlisting}
2611
2612 \subsubsection{pullToVoSpace}
2613 \label{subsubsec:pulltovospace}
2614 Import data into a VOSpace node.
2615
2616 This method asks the server to fetch data from a remote location.
2617
2618 The data transfer is initiated by the VOSpace service and transferred direct into the target Node.
2619
2620 The data source can be another VOSpace service, or a standard HTTP or FTP server.
2621
2622 The primary use case for this method is transferring data from one server or service to another.
2623
2624 This operation is OPTIONAL.
2625
2626 \paragraph{Request}
2627 A HTTP POST of a Job representation for the transfer to http://rest-endpoint/transfers
2628
2629 If a Node already exists at the target URI, then the data SHALL be imported into the existing Node and the Node properties SHALL be cleared unless the node is a ContainerNode.
2630
2631 If there is no Node at the target URI, then the service SHALL create a new Node using the uri, and the default xs:type for the space.
2632
2633 \paragraph{Response}
2634 The initial response is a HTTP 303 status code with the Location header keyword assigned to the created job.
2635
2636 \paragraph{Faults}\
2637 For all faults, the service shall set the PHASE to "ERROR" in the Job representation. The <errorSummary> element in the Job representation shall be set to the appropriate value for the fault type and the appropriate fault representation (see section 5.5) provided at the error URI: http://rest-endpoint/transfers/(jobid)/error.
2638
2639 \vspace{3mm}
2640 \begin{tabular}{ p{5cm} l p{4cm} }
2641 \textbf{Fault description} & \textbf{errorSummary} & \textbf{Fault representation} \\
2642 \hline
2643 Operation not supported & Operation Not Supported & OperationNotSupported \\
2644 \hline
2645 Operation fails & Internal Fault & InternalFault \\
2646 \hline
2647 User does not have permissions to perform the operation & Permission Denied & PermissionDenied \\
2648 \hline
2649 Service does not support the requested View & View Not Supported & ViewNotSupported \\
2650 \hline
2651 Service supports none of the requested Protocols & Protocol Not Supported &ProtocolNotSupported \\
2652 \hline
2653 Destination URI is invalid & Invalid URI & InvalidURI \\
2654 \hline
2655 A View parameter is invalid & Invalid Argument & InvalidArgument \\
2656 \hline
2657 A Protocol parameter is invalid & Invalid Argument & InvalidArgument \\
2658 \hline
2659 Data format does not match the requested View & Invalid Data & InvalidData \\
2660 \hline
2661 \end{tabular}
2662 \vspace{3mm}
2663
2664 \paragraph{Notes}
2665 If the Job request contains more than one protocol parameter, then the service MAY fail over to use one or more of the options if the first one fails. The service SHOULD try each protocol option in turn until one succeeds or all have been tried.
2666
2667 \paragraph{Example}
2668 pullToVoSpace
2669 \\[5px]
2670 \noindent
2671 The Job to be submitted (pullToVoSpace.xml):
2672 \begin{lstlisting}
2673 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
2674 <vos:target>vos://example.com!vospace/mydata1</vos:target>
2675 <vos:direction>pullToVoSpace</vos:direction>
2676 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpput">
2677 <vos:endpoint>http://anotherserver.example.com/here/is/the/data</vos:endpoint>
2678 </vos:protocol>
2679 </vos:transfer>
2680 \end{lstlisting}
2681 Request:
2682 \begin{lstlisting}
2683 > curl -v -X POST -d @pullToVoSpace.xml -H "Content-type: text/xml" "http://server.example.com/vospace/transfers"
2684 \end{lstlisting}
2685 Response:
2686 \begin{lstlisting}
2687 > POST /vospace/transfers HTTP/1.1
2688 > Content-type: text/xml
2689 >
2690 < HTTP/1.1 303 See Other
2691 < Location: http://server.example.com/vospace/transfers/m4ipu36gairz0dnl
2692 < Content-Type: text/plain
2693 <
2694 * Closing connection #0
2695 \end{lstlisting}
2696 The PENDING job can be seen by following the redirect to:
2697 \begin{lstlisting}
2698 > curl -v http://server.example.com/vospace/transfers/m4ipu36gairz0dnl
2699 \end{lstlisting}
2700 Response:
2701 \begin{lstlisting}
2702 > GET /vospace/transfers/m4ipu36gairz0dnl HTTP/1.1
2703 >
2704 < HTTP/1.1 200 OK
2705 < Content-Type: text/xml
2706 <
2707 <?xml version="1.0" encoding="UTF-8"?>
2708 <uws:job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
2709 <uws:jobId>m4ipu36gairz0dnl</uws:jobId>
2710 <uws:phase>PENDING</uws:phase>
2711 <uws:quote>2015-05-26T11:06:45.713</uws:quote>
2712 <uws:startTime xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xs:nil="true" />
2713 <uws:endTime xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xs:nil="true" />
2714 <uws:executionDuration>43200</uws:executionDuration>
2715 <uws:destruction>2015-06-01T23:06:45.713</uws:destruction>
2716 <uws:parameters />
2717 <uws:results />
2718 <uws:jobInfo>
2719 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
2720 <vos:target>vos://example.com!vospace/mydata1</vos:target>
2721 <vos:direction>pullToVoSpace</vos:direction>
2722 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpput">
2723 <vos:endpoint>http://anotherserver.example.com/here/is/the/data</vos:endpoint>
2724 </vos:protocol>
2725 </vos:transfer>
2726 </uws:jobInfo>
2727 </uws:job>
2728 \end{lstlisting}
2729 The job can now be started by posting PHASE=RUN:
2730 \begin{lstlisting}
2731 curl -v -X POST -d "PHASE=RUN" http://server.example.com/vospace/transfers/m4ipu36gairz0dnl/phase
2732 \end{lstlisting}
2733 Response:
2734 \begin{lstlisting}
2735 > POST /vospace/transfers/m4ipu36gairz0dnl/phase HTTP/1.1
2736 > Content-Type: text/xml
2737 >
2738 < HTTP/1.1 303 See Other
2739 < Location: http://server.examle.com/vospace/transfers/m4ipu36gairz0dnl
2740 < Content-Type: text/plain
2741 <
2742 \end{lstlisting}
2743 The EXECUTING job can be seen by following the redirect to:
2744 \begin{lstlisting}
2745 http://server.examle.com/vospace/transfers/m4ipu36gairz0dnl
2746 \end{lstlisting}
2747 Response:
2748 \begin{lstlisting}
2749 > GET /vospace/transfers/m4ipu36gairz0dnl HTTP/1.1
2750 >
2751 < HTTP/1.1 200 OK
2752 < Content-Type: text/xml
2753 <
2754 <?xml version="1.0" encoding="UTF-8"?>
2755 <uws:job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
2756 <uws:jobId>m4ipu36gairz0dnl</uws:jobId>
2757 <uws:phase>EXECUTING</uws:phase>
2758 <uws:quote>2015-05-26T11:06:45.713</uws:quote>
2759 <uws:startTime>2015-05-25T23:17:41.217</uws:startTime>
2760 <uws:endTime xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xs:nil="true" />
2761 <uws:executionDuration>43200</uws:executionDuration>
2762 <uws:destruction>2015-06-01T23:06:45.713</uws:destruction>
2763 <uws:parameters />
2764 <uws:results>
2765 <uws:result id="transferDetails" xlink:href="http://server.example.com/vospace/transfers/m4ipu36gairz0dnl/results/transferDetails" />
2766 <uws:result id="dataNode" xlink:href="vos://example.com!vospace/mydata1" />
2767 </uws:results>
2768 <uws:jobInfo>
2769 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
2770 <vos:target>vos://example.com!vospace/mydata1</vos:target>
2771 <vos:direction>pullFromVoSpace</vos:direction>
2772 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpput">
2773 <vos:endpoint>http://anotherserver.example.com/here/is/the/data</vos:endpoint>
2774 </vos:protocol>
2775 </vos:transfer>
2776 </uws:jobInfo>
2777 </uws:job>
2778 \end{lstlisting}
2779
2780 \subsubsection{pullFromVoSpace}
2781 \label{subsubsec:pullfromvospace}
2782 Request a set of URLs that the client can read data from.
2783
2784 The client requests access to the data in a Node, and the server SHALL respond with a set of URLs that the client can read the data from.
2785
2786 \paragraph{Request}
2787 A HTTP POST of a Job representation for the transfer to http://rest-endpoint/transfers or http://rest-endpoint/synctrans
2788 The transfer representation SHOULD contain details of the View and a list of the Protocols that the client would like to use.
2789
2790 The list of Protocols SHOULD not contain endpoint addresses; the service SHALL supply the endpoint addresses in the response.
2791
2792 The service SHALL ignore any of the requested protocols and security methods that it does not understand or is unable to support.
2793
2794 A pullFromVoSpace transfer may be initiated with an HTTP POST of a Job representation of the transfer to http://rest-endpoint/transfers. The service SHALL respond with a redirect to the newly created job. (See Example 1)
2795
2796 A pullFromVoSpace transfer may be initiated with an HTTP POST of a Job representation of the transfer to http://rest-endpoint/synctrans. The service SHALL respond with a redirect to the transfer details of the job. (See Example 2)
2797
2798 A pullFromVoSpace transfer may be initiated with an HTTP POST or GET to http://rest-endpoint/synctrans with the following URL query parameters:
2799 \begin{itemize}
2800 \item \emph{TARGET}: The value is the URI of the target node
2801 \begin{itemize}
2802 \item Example: vos://example.com$\mathtt{\sim}$vospace/mydata1
2803 \end{itemize}
2804 \item \emph{DIRECTION}: pullFromVoSpace
2805 \item \emph{PROTOCOL}: The standard URI of the protocol to use (see section ~\ref{subsubsec:standard protocols})
2806 \begin{itemize}
2807 \item Example: ivo://ivoa.net/vospace/core\#httpget
2808 \end{itemize}
2809 \end{itemize}
2810
2811 The following optional parameters may also be included:
2812 \begin{itemize}
2813 \item \emph{VIEW}: The standard URI of the view to use
2814 \begin{itemize}
2815 \item Example: ivo://ivoa.net/vospace/core\#cutoutview
2816 \end{itemize}
2817 \item \emph{SECURITYMETHOD}: The standard URI of the security method to use
2818 \begin{itemize}
2819 \item Example: ivo://ivoa.net/sso\#tls-with-certificate
2820 \end{itemize}
2821 \item \emph{REQUEST=redirect}: If supplied, the service will issue an immediate redirect to the preferred endpoint matching the transfer request.
2822 \end{itemize}
2823
2824
2825 The service SHALL respond with the job containing the transfer results in the response body. (See Example 3)
2826 If the parameter key value REQUEST=redirect is included with the other transfer parameters, the service SHALL respond with an immediate redirect to the preferred protocol endpoint for data download. (See Example 4)
2827
2828 There is also an alternate convenience mode of for full data download using view=data on the http://rest-endpoint/nodes resource (This alternative is now deprecated and will be removed in v3.0. This convenience mode has been replaced with the REQUEST=redirect functionality)
2829 \begin{itemize}
2830 \item A HTTP GET to the node URL that wants to be read with a parameter of "view = data": \\*
2831 http://rest-endpoint/nodes/path?view=data
2832 \end{itemize}
2833
2834 Clients may also use the "view" parameter on the getNode operation. Services may support different types of views for particular purposes. e.g., "view=rss" to identify a RSS feed on the resource.
2835
2836 \paragraph{Response}
2837 The initial response for the UWS mode is a HTTP 303 status code with the Location header keyword assigned to the created job
2838 The service SHALL select which of the requested Protocols it is willing to provide and fill in the operational details for each one in the transfer result representation - this SHOULD normally include specifying the source URL of the transfer protocol endpoint.
2839
2840 The service response SHOULD not include any Protocols that it is unable to support.
2841
2842 The transfer results representation can be retrieved directly from the link reported in the Results List, available either from the results endpoint - http://rest-endpoint/transfers/(jobid)/results - or as part of the full Job representation for the completed transfer available from http://rest-endpoint/transfers/(jobid). In the latter case, the result element in the Results List SHALL have an id of "transferDetails":
2843 \begin{lstlisting}
2844 <uws:job>
2845 ...
2846 <uws:results>
2847 <uws:result id="transferDetails" xlink:href="http://rest-endpoint/transfers/(jobid)/results/details1"/>
2848 </uws:results>
2849 ...
2850 < /uws:job>
2851 \end{lstlisting}
2852 If the transfer was initiated with a HTTP POST to http://rest-endpoint/sync then the response is:
2853 \begin{itemize}
2854 \item A HTTP 303 status code with the Location header keyword assigned to the endpoint: http://rest-endpoint/transfers/(jobid)/results/transferDetails.
2855 \end{itemize}
2856 The HTTP 303 redirect points to a transfer representation with the required transfer details and endpoints.
2857 If the transfer was initiated with a HTTP POST to http://rest-rendpoint/sync with transfer information TARGET, DIRECTION, and PROTOCOL supplied as query string parameters, the service may respond with the transfer details directly. If the parameter REQUEST=redirect is also provided in this POST, then the service may respond with a redirect to a preferred endpoint (example below).
2858
2859 \paragraph{Faults}
2860 For all faults using the UWS mode, the service shall set the PHASE to "ERROR" in the Job representation. The <errorSummary> element in the Job representation shall be set to the appropriate value for the fault type and the appropriate fault representation (see section 5.5) provided at the error URI: http://rest-endpoint/transfers/(jobid)/error.
2861
2862 \vspace{3mm}
2863 \begin{tabular}{ p{5cm} l p{4cm} }
2864 \textbf{Fault description} & \textbf{errorSummary} & \textbf{Fault representation} \\
2865 \hline
2866 Operation fails & Internal Fault & InternalFault \\
2867 \hline
2868 User does not have permissions to perform the operation & Permission Denied & PermissionDenied \\
2869 \hline
2870 Source Node does not exist & Node Not Found & NodeNotFound \\
2871 \hline
2872 Service does not support the requested View & View Not Supported & ViewNotSupported \\
2873 \hline
2874 Service supports none of the requested Protocols & Protocol Not Supported &ProtocolNotSupported \\
2875 \hline
2876 Destination URI is invalid & Invalid URI & InvalidURI \\
2877 \hline
2878 A View parameter is invalid & Invalid Argument & InvalidArgument \\
2879 \hline
2880 A Protocol parameter is invalid & Invalid Argument & InvalidArgument \\
2881 \hline
2882 \end{tabular}
2883 \vspace{3mm}
2884
2885 If an error occurs with the synchronous convenience mode, the resulting transfers document SHOULD have no protocols. The client can then retrieve the Job representation for error information as with asynchronous transfers.
2886
2887 If an error occurs with the synchronous convenience mode where the preferred endpoint is immediately returned as a redirect, the error information is returned directly in the response body with the associated HTTP status code.
2888
2889 \paragraph{Notes}
2890 The endpoint URLs supplied in the UWS response SHOULD be considered as 'one shot' URLs. A VOSpace service connected to a standard web server MAY return the public URL for the data. However, a different implementation MAY create a unique single use URL specifically for this transfer.
2891
2892 \paragraph{Example 1}
2893 pullFromVoSpace over the asynchronous endpoint
2894 \\[5px]
2895 \noindent
2896 The Job to be submitted (pullFromVoSpace.xml):
2897 \begin{lstlisting}
2898 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
2899 <vos:target>vos://example.com!vospace/mydata1</vos:target>
2900 <vos:direction>pullFromVoSpace</vos:direction>
2901 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpget" />
2902 </vos:transfer>
2903 \end{lstlisting}
2904 Request:
2905 \begin{lstlisting}
2906 > curl -v -X POST -d @pullFromVoSpace.xml -H "Content-type: text/xml" "http://server.example.com/vospace/transfers"
2907 \end{lstlisting}
2908 Response:
2909 \begin{lstlisting}
2910 > POST /vospace/transfers HTTP/1.1
2911 > Content-type: text/xml
2912 >
2913 < HTTP/1.1 303 See Other
2914 < Location: http://server.example.com/vospace/transfers/m4ipu36gairz0dnl
2915 < Content-Type: text/plain
2916 <
2917 * Closing connection #0
2918 \end{lstlisting}
2919 The PENDING job can be seen by following the redirect to:
2920 \begin{lstlisting}
2921 > curl -v http://server.example.com/vospace/transfers/m4ipu36gairz0dnl
2922 \end{lstlisting}
2923 Response:
2924 \begin{lstlisting}
2925 > GET /vospace/transfers/m4ipu36gairz0dnl HTTP/1.1
2926 >
2927 < HTTP/1.1 200 OK
2928 < Content-Type: text/xml
2929 <
2930 <?xml version="1.0" encoding="UTF-8"?>
2931 <uws:job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
2932 <uws:jobId>m4ipu36gairz0dnl</uws:jobId>
2933 <uws:phase>PENDING</uws:phase>
2934 <uws:quote>2015-05-26T11:06:45.713</uws:quote>
2935 <uws:startTime xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xs:nil="true" />
2936 <uws:endTime xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xs:nil="true" />
2937 <uws:executionDuration>43200</uws:executionDuration>
2938 <uws:destruction>2015-06-01T23:06:45.713</uws:destruction>
2939 <uws:parameters />
2940 <uws:results />
2941 <uws:jobInfo>
2942 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
2943 <vos:target>vos://example.com!vospace/mydata1</vos:target>
2944 <vos:direction>pullFromVoSpace</vos:direction>
2945 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpget" />
2946 </vos:transfer>
2947 </uws:jobInfo>
2948 </uws:job>
2949 \end{lstlisting}
2950 The job can now be started by posting PHASE=RUN:
2951 \begin{lstlisting}
2952 curl -v -X POST -d "PHASE=RUN" http://server.example.com/vospace/transfers/m4ipu36gairz0dnl/phase
2953 \end{lstlisting}
2954 Response:
2955 \begin{lstlisting}
2956 > POST /vospace/transfers/m4ipu36gairz0dnl/phase HTTP/1.1
2957 > Content-Type: text/xml
2958 >
2959 < HTTP/1.1 303 See Other
2960 < Location: http://server.examle.com/vospace/transfers/m4ipu36gairz0dnl
2961 < Content-Type: text/plain
2962 <
2963 \end{lstlisting}
2964 The EXECUTING job can be seen by following the redirect to:
2965 \begin{lstlisting}
2966 http://server.examle.com/vospace/transfers/m4ipu36gairz0dnl
2967 \end{lstlisting}
2968 Response:
2969 \begin{lstlisting}
2970 > GET /vospace/transfers/m4ipu36gairz0dnl HTTP/1.1
2971 >
2972 < HTTP/1.1 200 OK
2973 < Content-Type: text/xml
2974 <
2975 <?xml version="1.0" encoding="UTF-8"?>
2976 <uws:job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
2977 <uws:jobId>m4ipu36gairz0dnl</uws:jobId>
2978 <uws:phase>EXECUTING</uws:phase>
2979 <uws:quote>2015-05-26T11:06:45.713</uws:quote>
2980 <uws:startTime>2015-05-25T23:17:41.217</uws:startTime>
2981 <uws:endTime xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xs:nil="true" />
2982 <uws:executionDuration>43200</uws:executionDuration>
2983 <uws:destruction>2015-06-01T23:06:45.713</uws:destruction>
2984 <uws:parameters />
2985 <uws:results>
2986 <uws:result id="transferDetails" xlink:href="http://server.example.com/vospace/transfers/m4ipu36gairz0dnl/results/transferDetails" />
2987 <uws:result id="dataNode" xlink:href="vos://example.com!vospace/mydata1" />
2988 </uws:results>
2989 <uws:jobInfo>
2990 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
2991 <vos:target>vos://example.com!vospace/mydata1</vos:target>
2992 <vos:direction>pullFromVoSpace</vos:direction>
2993 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpget" />
2994 </vos:transfer>
2995 </uws:jobInfo>
2996 </uws:job>
2997 \end{lstlisting}
2998 The details of the transfer negotiation can be see by following the \emph{transferDetails} result:
2999 \begin{lstlisting}
3000 > curl -v http://server.example.com/vospace/transfers/m4ipu36gairz0dnl/results/transferDetails
3001 \end{lstlisting}
3002 Response:
3003 \begin{lstlisting}
3004 > GET /vospace/transfers/m4ipu36gairz0dnl/results/transferDetails HTTP/1.1
3005 >
3006 < HTTP/1.1 200 OK
3007 < Content-Type: text/xml;charset=UTF-8
3008 <
3009 <?xml version="1.0" encoding="UTF-8"?>
3010 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
3011 <vos:target>vos://example.com!vospace/mydata1</vos:target>
3012 <vos:direction>pullFromVoSpace</vos:direction>
3013 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpget">
3014 <vos:endpoint>http://storage1.example.com/trans/mydata1</vos:endpoint>
3015 </vos:protocol>
3016 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpget">
3017 <vos:endpoint>http://storage2.example.com/mydata1</vos:endpoint>
3018 </vos:protocol>
3019 </vos:transfer>
3020 \end{lstlisting}
3021 The file can now be retrieved over HTTP GET from one of the endpoints listed in the transfer details.
3022 \begin{lstlisting}
3023 > curl -v -o mydata1 "http://storage1.example.com/mydata1"
3024 \end{lstlisting}
3025 Response:
3026 \begin{lstlisting}
3027 > GET /mydata1 HTTP/1.1
3028 >
3029 < HTTP/1.1 200 OK
3030 < Content-Type: text/plain;charset=UTF-8
3031 <
3032 [data not shown]
3033 \end{lstlisting}
3034 On successful file transfer completion the job will be COMPLETED:
3035 \begin{lstlisting}
3036 curl -v http://server.examle.com/vospace/transfers/m4ipu36gairz0dnl/phase
3037 \end{lstlisting}
3038 Response:
3039 \begin{lstlisting}
3040 > GET /vospace/transfers/m4ipu36gairz0dnl/phase HTTP/1.1
3041 >
3042 < HTTP/1.1 200 OK
3043 < Content-Type: text/plain;charset=UTF-8
3044 <
3045 COMPLETED
3046 \end{lstlisting}
3047 \paragraph{Example 2}
3048 pullFromVoSpace over the synchronous endpoint
3049 \\[5px]
3050 \noindent
3051 The Job to be submitted (pullFromVoSpace.xml):
3052 \begin{lstlisting}
3053 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
3054 <vos:target>vos://example.com!vospace/mydata1</vos:target>
3055 <vos:direction>pullFromVoSpace</vos:direction>
3056 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpget" />
3057 </vos:transfer>
3058 \end{lstlisting}
3059 Request:
3060 \begin{lstlisting}
3061 > curl -v -X POST -d @pullFromVoSpace.xml -H "Content-type: text/xml" "http://server.example.com/vospace/synctrans"
3062 \end{lstlisting}
3063 Response:
3064 \begin{lstlisting}
3065 > POST /vospace/synctrans HTTP/1.1
3066 > Content-Type: text/xml
3067 >
3068 < HTTP/1.1 303 See Other
3069 < Location: http://server.example.com/vospace/transfers/m4ipu36gairz0dnl/results/transferDetails
3070 < Content-Type: text/plain
3071 <
3072 \end{lstlisting}
3073 The negotiated transfer details can be seen by following the redirect to:
3074 \begin{lstlisting}
3075 http://server.examlpe.com/vospace/transfers/m4ipu36gairz0dnl/results/transferDetails
3076 \end{lstlisting}
3077 Request:
3078 \begin{lstlisting}
3079 > curl -v http://server.example.com/vospace/transfers/m4ipu36gairz0dnl/results/transferDetails
3080 \end{lstlisting}
3081 Response:
3082 \begin{lstlisting}
3083 > GET /vospace/transfers/m4ipu36gairz0dnl/results/transferDetails HTTP/1.1
3084 >
3085 < HTTP/1.1 200 OK
3086 < Content-Type: text/xml;charset=UTF-8
3087 <
3088 <?xml version="1.0" encoding="UTF-8"?>
3089 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
3090 <vos:target>vos://example.com!vospace/mydata1</vos:target>
3091 <vos:direction>pullFromVoSpace</vos:direction>
3092 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpget">
3093 <vos:endpoint>http://storage1.example.com/trans/mydata1</vos:endpoint>
3094 </vos:protocol>
3095 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpget">
3096 <vos:endpoint>http://storage2.example.com/mydata1</vos:endpoint>
3097 </vos:protocol>
3098 </vos:transfer>
3099 \end{lstlisting}
3100 The file can be retrieved with an HTTP GET to one of the endpoints:
3101 \begin{lstlisting}
3102 curl -v -o mydata1 http://storage1.example.com/mydata1
3103 \end{lstlisting}
3104 Response:
3105 \begin{lstlisting}
3106 > GET /mydata1 HTTP/1.1
3107 >
3108 < HTTP/1.1 200 OK
3109 < Content-Type: text/plain;charset=UTF-8
3110 <
3111 [data not shown]
3112 \end{lstlisting}
3113
3114 \paragraph{Example 3}
3115 pullFromVoSpace over the synchronous endpoint with securityMethod
3116 \\[5px]
3117 \noindent
3118 A transfer request for endpoints supporting basic authentication over HTTP or TLS with a client certificate over SSL.\\
3119 The Job to be submitted (pullFromVoSpace.xml):
3120 \begin{lstlisting}
3121 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
3122 <vos:target>vos://example.com!vospace/mydata1</vos:target>
3123 <vos:direction>pullFromVoSpace</vos:direction>
3124 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpsget">
3125 <vos:securityMethod uri="ivo://ivoa.net/sso#tls-with-certificate"/>
3126 </vos:protocol>
3127 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpget">
3128 <vos:securityMethod uri="uri="http://www.w3.org/Protocols/HTTP/1.0/spec/html#BasicAA"/>
3129 </vos:protocol>
3130 </vos:transfer>
3131 \end{lstlisting}
3132 Request:
3133 \begin{lstlisting}
3134 > curl -v -X POST -d @pullFromVoSpace.xml -H "Content-type: text/xml" "http://server.example.com/vospace/synctrans"
3135 \end{lstlisting}
3136 Response:
3137 \begin{lstlisting}
3138 > POST /vospace/synctrans HTTP/1.1
3139 > Content-Type: text/xml
3140 >
3141 < HTTP/1.1 303 See Other
3142 < Location: http://server.example.com/vospace/transfers/zkqzpftmufdi8luh/results/transferDetails
3143 < Content-Type: text/plain
3144 <
3145 \end{lstlisting}
3146 The negotiated transfer details can be seen by following the redirect to:
3147 \begin{lstlisting}
3148 http://server.examlpe.com/vospace/transfers/zkqzpftmufdi8luh/results/transferDetails
3149 \end{lstlisting}
3150 Request:
3151 \begin{lstlisting}
3152 > curl -v http://server.example.com/vospace/transfers/zkqzpftmufdi8luh/results/transferDetails
3153 \end{lstlisting}
3154 Response:
3155 \begin{lstlisting}
3156 > GET /vospace/transfers/zkqzpftmufdi8luh/results/transferDetails HTTP/1.1
3157 >
3158 < HTTP/1.1 200 OK
3159 < Content-Type: text/xml;charset=UTF-8
3160 <
3161 <?xml version="1.0" encoding="UTF-8"?>
3162 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
3163 <vos:target>vos://example.com!vospace/mydata1</vos:target>
3164 <vos:direction>pullFromVoSpace</vos:direction>
3165 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpsget">
3166 <vos:endpoint>https://storage1.example.com/trans/mydata1</vos:endpoint>
3167 <vos:securityMethod uri="ivo://ivoa.net/sso#tls-with-certificate"/>
3168 </vos:protocol>
3169 </vos:transfer>
3170 \end{lstlisting}
3171 The service has replied with a single HTTPS endpoint that support TLS with client certificates.\\
3172 The file can be retrieved with an HTTPS GET to the endpoint:
3173 \begin{lstlisting}
3174 curl -v -o mydata1 -E mycert.pem https://storage1.example.com/mydata1
3175 \end{lstlisting}
3176 Response:
3177 \begin{lstlisting}
3178 > GET /mydata1 HTTP/1.1
3179 >
3180 < HTTP/1.1 200 OK
3181 < Content-Type: text/plain;charset=UTF-8
3182 <
3183 [data not shown]
3184 \end{lstlisting}
3185
3186 \paragraph{Example 4}
3187 pullFromVoSpace over the synchronous endpoint with URL parameters
3188 \\[5px]
3189 \noindent
3190 Request:
3191 \begin{lstlisting}
3192 curl -v -X POST "http://server.example.com/vospace/synctrans?TARGET=vos://example.com~vospace/mydata1&DIRECTION=pullFromVoSpace&PROTOCOL=ivo://ivoa.net/vospace/core%23httpget"
3193 \end{lstlisting}
3194 (Note that the \# sign in PROTOCOL is URL encoded as \%23 and that the alternate separator `$\mathtt{\sim}$' is used instead of `!' in the TARGET) \\
3195 \\
3196 Response:
3197 \begin{lstlisting}
3198 > POST /vospace/synctrans?TARGET=vos://example.com~vospace/mydata1&DIRECTION=pullFromVoSpace&PROTOCOL=ivo://ivoa.net/vospace/core\%23httpget HTTP/1.1
3199 >
3200 < HTTP/1.1 200 OK
3201 < Content-Type: text/xml;charset=UTF-8
3202 <
3203 <?xml version="1.0" encoding="UTF-8"?>
3204 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
3205 <vos:target>vos://example.com!vospace/mydata1</vos:target>
3206 <vos:direction>pullFromVoSpace</vos:direction>
3207 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpget">
3208 <vos:endpoint>http://storage1.example.com/trans/mydata1</vos:endpoint>
3209 </vos:protocol>
3210 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpget">
3211 <vos:endpoint>http://storage2.example.com/mydata1</vos:endpoint>
3212 </vos:protocol>
3213 </vos:transfer>
3214 \end{lstlisting}
3215 The file can be retrieved with an HTTP GET to one of the endpoints:
3216 \begin{lstlisting}
3217 curl -v -o mydata1 http://storage1.example.com/mydata1
3218 \end{lstlisting}
3219 Response:
3220 \begin{lstlisting}
3221 > GET /mydata1 HTTP/1.1
3222 >
3223 < HTTP/1.1 200 OK
3224 < Content-Type: text/plain;charset=UTF-8
3225 <
3226 [data not shown]
3227 \end{lstlisting}
3228
3229 \paragraph{Example 5}
3230 pullFromVoSpace over the synchronous endpoint with URL parameters and REQUEST=redirect
3231 \\[5px]
3232 \noindent
3233 Request:
3234 \begin{lstlisting}
3235 curl -v -X POST "http://server.example.com/vospace/synctrans?TARGET=vos://example.com~vospace/mydata1&DIRECTION=pullFromVoSpace&PROTOCOL=ivo://ivoa.net/vospace/core%23httpget&REQUEST=redirect"
3236 \end{lstlisting}
3237 (Note that the \# sign in PROTOCOL is URL encoded as \%23 and the alternate separator `$\mathtt{\sim}$' is used instead of `!' in the TARGET) \\
3238 \\
3239 Response:
3240 \begin{lstlisting}
3241 > POST /vospace/synctrans?TARGET=vos://example.com~vospace/mydata1&DIRECTION=pullFromVoSpace&PROTOCOL=ivo://ivoa.net/vospace/core\%23httpget&REQUEST=redirect HTTP/1.1
3242 <
3243 < HTTP/1.1 303 See Other
3244 < Location: http://storage1.example.com/mydata1
3245 < Content-Type: text/plain
3246 <
3247 \end{lstlisting}
3248 The file can be retrieved by following the redirect:
3249 \begin{lstlisting}
3250 curl -v -o mydata1 http://storage1.example.com/mydata1
3251 \end{lstlisting}
3252 Response:
3253 \begin{lstlisting}
3254 > GET /mydata1 HTTP/1.1
3255 >
3256 < HTTP/1.1 200 OK
3257 < Content-Type: text/plain;charset=UTF-8
3258 <
3259 [data not shown]
3260 \end{lstlisting}
3261
3262 \paragraph{Example 6}
3263 pullFromVoSpace over the synchronous endpoint with URL parameters, REQUEST=redirect and SecurityMethod
3264 \\[5px]
3265 \noindent
3266 Request:
3267 \begin{lstlisting}
3268 curl -v -X POST -E mycert.pem "https://server.example.com/vospace/synctrans?TARGET=vos://example.com~vospace/mydata1&DIRECTION=pullFromVoSpace&PROTOCOL=ivo://ivoa.net/vospace/core%23httpsget&REQUEST=redirect&SECURITYMETHOD=ivo://ivoa.net/sso%23tls-with-certificate"
3269 \end{lstlisting}
3270 Since the expected response is a redirect, the initial protocol on the post is HTTPS and the certificate is supplied.\\*
3271 (Note that the \# sign in PROTOCOL is URL encoded as \%23 and that the alternate separator `$\mathtt{\sim}$' is used instead of `!' in the TARGET) \\
3272 \\
3273 Response:
3274 \begin{lstlisting}
3275 > POST /vospace/synctrans?TARGET=vos://example.com~vospace/mydata1&DIRECTION=pullFromVoSpace&PROTOCOL=ivo://ivoa.net/vospace/core\%23httpget&REQUEST=redirect&SECURITYMETHOD=ivo://ivoa.net/sso%23tls-with-certificate HTTP/1.1
3276 >
3277 < HTTP/1.1 303 See Other
3278 < Location: https://storage1.example.com/mydata1
3279 < Content-Type: text/plain
3280 <
3281 \end{lstlisting}
3282 The file can be retrieved by following the redirect:
3283 \begin{lstlisting}
3284 curl -v -o mydata1 -E mycert.pem https://storage1.example.com/mydata1
3285 \end{lstlisting}
3286 Response:
3287 \begin{lstlisting}
3288 > GET /mydata1 HTTP/1.1
3289 >
3290 < HTTP/1.1 200 OK
3291 < Content-Type: text/plain;charset=UTF-8
3292 <
3293 [data not shown]
3294 \end{lstlisting}
3295
3296 \subsubsection{pushFromVoSpace}
3297 \label{subsubsec:pushfromvospace}
3298 Ask the server to send data to a remote location.
3299
3300 The client supplies a list of URLs and asks the server to send the data to the remote location.
3301
3302 The transfer is initiated by the server, and the data transferred direct from the server to the remote location.
3303
3304 This operation is OPTIONAL.
3305
3306 \paragraph{Request}
3307 A HTTP POST of a Job representation for the transfer to http://rest-endpoint/transfers
3308
3309 \paragraph{Response}
3310 The initial response is a HTTP 303 status code with the Location header keyword assigned to the created job.
3311 5.4.4.3 Faults
3312
3313 \vspace{3mm}
3314 \begin{tabular}{ p{5cm} l p{4cm} }
3315 \textbf{Fault description} & \textbf{errorSummary} & \textbf{Fault representation} \\
3316 \hline
3317 Operation not supported & Operation Not Supported & OperationNotSupported \\
3318 \hline
3319 Operation fails & Internal Fault & InternalFault \\
3320 \hline
3321 User does not have permissions to perform the operation & Permission Denied & PermissionDenied \\
3322 \hline
3323 Source Node does not exist & Node Not Found & NodeNotFound \\
3324 \hline
3325 Service does not support the requested View & View Not Supported & ViewNotSupported \\
3326 \hline
3327 Service supports none of the requested Protocols & Protocol Not Supported &ProtocolNotSupported \\
3328 \hline
3329 Destination URI is invalid & Invalid URI & InvalidURI \\
3330 \hline
3331 A View parameter is invalid & Invalid Argument & InvalidArgument \\
3332 \hline
3333 A Protocol parameter is invalid & Invalid Argument & InvalidArgument \\
3334 \hline
3335 Data transfer does not complete & Transfer Failed & TransferFailed \\
3336 \hline
3337 \end{tabular}
3338 \vspace{3mm}
3339
3340 \paragraph{Notes}
3341 If the Job request contains more than one protocol parameter then the service MAY fail over to use one or more of the options if the first one fails. The service SHOULD try each protocol option in turn until one succeeds or all have been tried.
3342
3343 \paragraph{Example}
3344 pushFromVoSpace
3345 \\[5px]
3346 \noindent
3347 The Job to be submitted (pushFromVoSpace.xml):
3348 \begin{lstlisting}
3349 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
3350 <vos:target>vos://example.com!vospace/mydata1</vos:target>
3351 <vos:direction>pushFromVoSpace</vos:direction>
3352 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpput">
3353 <vos:endpoint>http://anotherserver1.example.com/put/the/data/here</vos:endpoint>
3354 </vos:protocol>
3355 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpput">
3356 <vos:endpoint>http://anotherserver2.example.com/put/the/data/here</vos:endpoint>
3357 </vos:protocol>
3358 </vos:transfer>
3359 \end{lstlisting}
3360 Request:
3361 \begin{lstlisting}
3362 > curl -v -X POST -d @pushFromVoSpace.xml -H "Content-type: text/xml" "http://server.example.com/vospace/transfers"
3363 \end{lstlisting}
3364 Response:
3365 \begin{lstlisting}
3366 > POST /vospace/transfers HTTP/1.1
3367 > Content-type: text/xml
3368 >
3369 < HTTP/1.1 303 See Other
3370 < Location: http://server.example.com/vospace/transfers/m4ipu36gairz0dnl
3371 < Content-Type: text/plain
3372 <
3373 * Closing connection #0
3374 \end{lstlisting}
3375 The PENDING job can be seen by following the redirect to:
3376 \begin{lstlisting}
3377 > curl -v http://server.example.com/vospace/transfers/m4ipu36gairz0dnl
3378 \end{lstlisting}
3379 Response:
3380 \begin{lstlisting}
3381 > GET /vospace/transfers/m4ipu36gairz0dnl HTTP/1.1
3382 >
3383 < HTTP/1.1 200 OK
3384 < Content-Type: text/xml
3385 <
3386 <?xml version="1.0" encoding="UTF-8"?>
3387 <uws:job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
3388 <uws:jobId>m4ipu36gairz0dnl</uws:jobId>
3389 <uws:phase>PENDING</uws:phase>
3390 <uws:quote>2015-05-26T11:06:45.713</uws:quote>
3391 <uws:startTime xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xs:nil="true" />
3392 <uws:endTime xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xs:nil="true" />
3393 <uws:executionDuration>43200</uws:executionDuration>
3394 <uws:destruction>2015-06-01T23:06:45.713</uws:destruction>
3395 <uws:parameters />
3396 <uws:results />
3397 <uws:jobInfo>
3398 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
3399 <vos:target>vos://example.com!vospace/mydata1</vos:target>
3400 <vos:direction>pushFromVoSpace</vos:direction>
3401 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpput">
3402 <vos:endpoint>http://anotherserver1.example.com/put/the/data/here</vos:endpoint>
3403 </vos:protocol>
3404 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpput">
3405 <vos:endpoint>http://anotherserver2.example.com/put/the/data/here</vos:endpoint>
3406 </vos:protocol>
3407 </vos:transfer>
3408 </uws:jobInfo>
3409 </uws:job>
3410 \end{lstlisting}
3411 The job can now be started by posting PHASE=RUN:
3412 \begin{lstlisting}
3413 curl -v -X POST -d "PHASE=RUN" http://server.example.com/vospace/transfers/m4ipu36gairz0dnl/phase
3414 \end{lstlisting}
3415 Response:
3416 \begin{lstlisting}
3417 > POST /vospace/transfers/m4ipu36gairz0dnl/phase HTTP/1.1
3418 > Content-Type: text/xml
3419 >
3420 < HTTP/1.1 303 See Other
3421 < Location: http://server.examle.com/vospace/transfers/m4ipu36gairz0dnl
3422 < Content-Type: text/plain
3423 <
3424 \end{lstlisting}
3425 The EXECUTING job can be seen by following the redirect to:
3426 \begin{lstlisting}
3427 http://server.examle.com/vospace/transfers/m4ipu36gairz0dnl
3428 \end{lstlisting}
3429 Response:
3430 \begin{lstlisting}
3431 > GET /vospace/transfers/m4ipu36gairz0dnl HTTP/1.1
3432 >
3433 < HTTP/1.1 200 OK
3434 < Content-Type: text/xml
3435 <
3436 <?xml version="1.0" encoding="UTF-8"?>
3437 <uws:job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
3438 <uws:jobId>m4ipu36gairz0dnl</uws:jobId>
3439 <uws:phase>EXECUTING</uws:phase>
3440 <uws:quote>2015-05-26T11:06:45.713</uws:quote>
3441 <uws:startTime>2015-05-25T23:17:41.217</uws:startTime>
3442 <uws:endTime xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xs:nil="true" />
3443 <uws:executionDuration>43200</uws:executionDuration>
3444 <uws:destruction>2015-06-01T23:06:45.713</uws:destruction>
3445 <uws:parameters />
3446 <uws:results>
3447 <uws:result id="transferDetails" xlink:href="http://server.example.com/vospace/transfers/m4ipu36gairz0dnl/results/transferDetails" />
3448 <uws:result id="dataNode" xlink:href="vos://example.com!vospace/mydata1" />
3449 </uws:results>
3450 <uws:jobInfo>
3451 <vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.1">
3452 <vos:target>vos://example.com!vospace/mydata1</vos:target>
3453 <vos:direction>pushFromVoSpace</vos:direction>
3454 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpput">
3455 <vos:endpoint>http://anotherserver1.example.com/put/the/data/here</vos:endpoint>
3456 </vos:protocol>
3457 <vos:protocol uri="ivo://ivoa.net/vospace/core#httpput">
3458 <vos:endpoint>http://anotherserver2.example.com/put/the/data/here</vos:endpoint>
3459 </vos:protocol>
3460 </vos:transfer>
3461 </uws:jobInfo>
3462 </uws:job>
3463 \end{lstlisting}
3464
3465 \subsection{Fault arguments}
3466 \label{subsec:fault arguments}
3467 Faults reported by a VOSpace service SHALL contain the following information:
3468
3469 \paragraph{InternalFault}
3470 This is thrown with a description of the cause of the fault.
3471
3472 \paragraph{PermissionDenied}
3473 This is thrown with a description of why the credentials (if any were provided) were rejected.
3474
3475 \paragraph{InvalidURI}
3476 This is thrown with details of the invalid URI.
3477
3478 \paragraph{NodeNotFound}
3479 This is thrown with the URI of the missing Node.
3480
3481 \paragraph{DuplicateNode}
3482 This is thrown with the URI of the duplicate Node.
3483
3484 \paragraph{InvalidToken}
3485 This is thrown with the invalid token.
3486
3487 \paragraph{InvalidArgument}
3488 This is thrown with a description of the invalid argument, including the View or Protocol URI and the name and value of the parameter that caused the fault.
3489
3490 \paragraph{TypeNotSupported}
3491 This is thrown with the QName of the unsupported type.
3492
3493 \paragraph{ViewNotSupported}
3494 This is thrown with the uri of the View.
3495
3496 \paragraph{InvalidData}
3497 This is thrown with any error message that the data parser produced.
3498
3499 \paragraph{LinkFoundFault}
3500 The fault details must contain the full details of the LinkNode.
3501
3502 \section{Changes since last version}
3503 \label{sec:changes since last version}
3504
3505 \paragraph{From version 2.1-20150601:}
3506 \begin{itemize}
3507 \item Added REQUEST=redirect for further optimized pullFromVoSpace
3508 \item Commented-out search and find nodes until use cases and implementations are presented
3509 \item Changed pullToVoSpace, pushFromVoSpace to be client orchestrated.
3510 \item Removed asynchronous pushToVoSpace and pullToVoSpace (? TBD)
3511 \item Changed Transfer in XSD to accept parameters.
3512 \item Recreated and expanded all webservice operation examples
3513 \item Changed XSD element authType to SecurityMethod to match IVOA standard.
3514 \item Fixed text inconsistencies
3515 \item Ported source to ivoatex format
3516 \end{itemize}
3517
3518 \appendix
3519
3520 \section{Machine readable definitions}
3521 \label{sec:machine readable definitions}
3522 \subsection{Message schema}
3523 \label{subsec:message schema}
3524 XML Schema
3525 The requests and responses of a VOSpace 2.0 service shall adhere to the following XML Schema:
3526
3527 \lstinputlisting{VOSpace-2.1.xsd}
3528
3529 \section{Compliance matrix}
3530 \label{sec:compliance matrix}
3531 This table summarizes the mandatory behaviour required of a fully compliant VOSpace 2.1 service, i.e. those operations denoted as SHALL and MUST occurring. Note that for faults the general condition is specified but specific details should be checked in the relevant sections. Those associated with optional features are marked with an asterisk in the appropriate section reference - if the service implements an optional feature then it must show this mandatory behaviour.
3532
3533 \hskip-2.0cm\begin{tabular}{ | p {1cm} | p {11cm} | p {4cm} | }
3534 \hline
3535 \textbf{Item} & \textbf{Description} & \textbf{Occurs in section(s)} \\ \hline
3536 1 & VOSpace node identifiers are a URI with the scheme vos:// & ~\ref{sec:vospace identifiers} \\ \hline
3537 2 & The naming authority for a VOSpace node URI is the VOSpace service through which the node was created & ~\ref{sec:vospace identifiers} \\ \hline
3538 3 & "!" or "$\mathtt{\sim}$" are used consistently in VOSpace node URIs & ~\ref{sec:vospace identifiers} \\ \hline
3539 4 & "!" or "$\mathtt{\sim}$" are valid separator characters in service requests & ~\ref{sec:vospace identifiers} \\ \hline
3540 5 & All ancestors in a node hierarchy are resolvable as containers & ~\ref{sec:vospace identifiers} \\ \hline
3541 6 & The bit pattern for data stored in an UnstructuredDataNode is identical for read/write operations & ~\ref{subsec:nodes and node types}* \\ \hline
3542 7 & A Node has elements: uri, properties and capabilities & ~\ref{subsec:nodes and node types} \\ \hline
3543 8 & A DataNode has elements: uri, properties, capabilities, accepts, provides & ~\ref{subsec:nodes and node types} \\ \hline
3544 9 & A LinkNode has elements: uri, properties, capabilities and target & ~\ref{subsec:nodes and node types}* \\ \hline
3545 10 & A ContainerNode and a LinkNode have no data bytes associated with them & ~\ref{subsec:nodes and node types}* \\ \hline
3546 11 & A VOSpace service parses XML representations of all node types & ~\ref{subsec:nodes and node types} \\ \hline
3547 12 & A VOSpace services does not throw a XML parser error in response to requests about unsupported node types & ~\ref{subsec:nodes and node types} \\ \hline
3548 13 & A Property has elements:uri, endpoint and optional readonly flag & ~\ref{subsec:properties} \\ \hline
3549 14 & URIs must be valid (and unique) & ~\ref{subsubsec:property identifiers}, ~\ref{subsubsec:capability identifiers}, ~\ref{subsubsec:view identifiers}, ~\ref{subsubsec:protocol identifiers}, ~\ref{subsubsec:createnode}, ~\ref{subsubsec:pushtovospace}, ~\ref{subsubsec:pulltovospace} \\ \hline
3550 15 & A Capability has elements: uri, endpoint and param & ~\ref{subsec:capabilities} \\ \hline
3551 16 & Standard capabilities are represented by the specified URIs & ~\ref{subsubsec:standard capabilities} \\ \hline
3552 17 & Each Property is identified by a unique URI & ~\ref{subsubsec:property identifiers} \\ \hline
3553 18 & Each Capability is identified by a unique URI & ~\ref{subsubsec:capability identifiers} \\ \hline
3554 19 & Each View is identified by a unique URI & ~\ref{subsubsec:view identifiers} \\ \hline
3555 20 & Each Protocol is identified by a unique URI & ~\ref{subsubsec:protocol identifiers} \\ \hline
3556 21 & Standard views are represented by the specified URIs & ~\ref{subsubsec:default views} \\ \hline
3557 xx & Standard properties are represented by the specified URIs & ~\ref{subsubsec:standard properties} \\ \hline
3558 22 & Data imported with the default View is treated as a binary BLOB & ~\ref{subsubsec:default views} \\ \hline
3559 23 & Data exported with the default export View is returned in the most appropriate format & ~\ref{subsubsec:default views} \\ \hline
3560 24 & An archive format View on a ContainerNode provides access to the archive contents as children nodes of the container & ~\ref{subsubsec:container views}* \\ \hline
3561 25 & An archive format View specified in a data export operation on a ContainerNode will package the contents of the container and all its child nodes & ~\ref{subsubsec:container views}* \\ \hline
3562 \end{tabular}
3563
3564 \hskip-2.0cm\begin{tabular}{ | p {1cm} | p {11cm} | p {4cm} | }
3565 \hline
3566 \textbf{Item} & \textbf{Description} & \textbf{Occurs in section(s)} \\ \hline
3567 26 & A Protocol has elements: uri and and endpoint & ~\ref{subsec:protocols} \\ \hline
3568 27 & Standard Protocols are represented by the specified URIs & ~\ref{subsubsec:standard protocols} \\ \hline
3569 28 & A Transfer UWS Job representation has elements: target, direction, view, protocol and keepBytes & ~\ref{subsec:transfers} \\ \hline
3570 29 & A Transfer results representation has elements: target, direction, view, and protocol & ~\ref{subsec:transfers} \\ \hline
3571 30 & A server responds with a fault if it is unable to handle any of the requested protocols in a data transfer & ~\ref{subsubsec:service-initiated transfers}, ~\ref{subsubsec:client-initiated transfers} \\ \hline
3572 31 & A server uses each requested protocol only once in a data transfer & ~\ref{subsubsec:service-initiated transfers}, ~\ref{subsubsec:client-initiated transfers} \\ \hline
3573 32 & A data transfer is complete once a specified protocol is successful & ~\ref{subsubsec:service-initiated transfers}, ~\ref{subsubsec:client-initiated transfers} \\ \hline
3574 33 & A data transfer has failed if none of the specified protocols has been successful & ~\ref{subsubsec:service-initiated transfers}, ~\ref{subsubsec:client-initiated transfers} \\ \hline
3575 34 & A server updates the status flag in the UWS Job representation as appropriate & ~\ref{subsubsec:service-initiated transfers}, ~\ref{subsubsec:client-initiated transfers} \\ \hline
3576 % 35 & A Search UWS Job representation has elements: uri, limit, detail, matches and node & ~\ref{subsec:searches}* \\ \hline
3577 % 36 & A Search results representation has elements: nodes & ~\ref{subsec:searches}* \\ \hline
3578 35 & A VOSpace service has the REST bindings: properties, views, protocols, nodes, and transfers & ~\ref{subsec:rest bindings} \\ \hline
3579 36 & Access policies on a VOSpace service are declared in the registered metadata for the service & ~\ref{sec:access control} \\ \hline
3580 37 & VOSpace authentication employs IVOA SSO supported methods & ~\ref{sec:access control} \\ \hline
3581 38 & A VOSpace service supports the operations: getProtocols, getViews, getProperties, createNode, deleteNode, moveNode, copyNode, getNode, setNode, pullFromVoSpace. The following are optional operations: pushToVoSpace, pullToVoSpace, pushFromVoSpace & ~\ref{subsubsec:getprotocols}, ~\ref{subsubsec:getviews}, ~\ref{subsubsec:getproperties}, ~\ref{subsubsec:createnode}, ~\ref{subsubsec:movenode}, ~\ref{subsubsec:copynode}, ~\ref{subsubsec:deletenode}, ~\ref{subsubsec:getnode}, ~\ref{subsubsec:setnode}, ~\ref{subsubsec:pushtovospace}*, ~\ref{subsubsec:pushtovospace}*, ~\ref{subsubsec:pullfromvospace}, ~\ref{subsubsec:pushfromvospace}* \\ \hline
3582 39 & accepts and provides specify entities that the service supports & ~\ref{subsubsec:getprotocols}, ~\ref{subsubsec:getviews}, ~\ref{subsubsec:getproperties} \\ \hline
3583 40 & An autogenerated URI is specified as a result in the Results List & ~\ref{subsubsec:createnode}*, ~\ref{subsubsec:movenode}*, ~\ref{subsubsec:copynode}*, ~\ref{subsubsec:pushtovospace}* \\ \hline
3584 41 & Any data written to the reserved URI .null is discarded & ~\ref{subsec:rest bindings} \\ \hline
3585 42 & accepts is filled in based on service capabilities & ~\ref{subsubsec:createnode} \\ \hline
3586 43 & If a container is deleted then so are its children & ~\ref{subsubsec:deletenode} \\ \hline
3587 44 & If a container is listed, only direct children are listed & ~\ref{subsubsec:getnode} \\ \hline
3588 45 & Results are drawn from the same ordered sequence in any ordering imposed by the server & ~\ref{subsubsec:getnode} \\ \hline
3589 46 & Regex expressions comply with POSIX conventions & ~\ref{subsec:searches} \\ \hline
3590 47 & Moving a container moves its children as well & ~\ref{subsubsec:movenode} \\ \hline
3591 \end{tabular}
3592
3593 \hskip-2.0cm\begin{tabular}{ | p {1cm} | p {11cm} | p {4cm} | }
3594 \hline
3595 \textbf{Item} & \textbf{Description} & \textbf{Occurs in section(s)} \\ \hline
3596 48 & Importing data into an existing container puts the new data within the container & ~\ref{subsubsec:pushtovospace} \\ \hline
3597 49 & Node types are not changed when a node is moved or copied & ~\ref{subsubsec:movenode}, ~\ref{subsubsec:copynode} \\ \hline
3598 50 & Copying a container copies its children as well & ~\ref{subsubsec:copynode} \\ \hline
3599 51 & Importing data into an existing node overwrites any preexisting data (unless it is a container) & ~\ref{subsubsec:pushtovospace}*, ~\ref{subsubsec:pulltovospace}* \\ \hline
3600 52 & A HTTP 200 status code is returned if the operation completes successfully & ~\ref{subsubsec:getprotocols}, ~\ref{subsubsec:getviews}, ~\ref{subsubsec:getproperties}, ~\ref{subsubsec:createnode}, ~\ref{subsubsec:deletenode}, ~\ref{subsubsec:getnode}, ~\ref{subsubsec:setnode} \\ \hline
3601 53 & A HTTP 303 status code is returned if the operation completes successfully & ~\ref{subsubsec:movenode}, ~\ref{subsubsec:copynode}, ~\ref{subsubsec:findnodes}*, ~\ref{subsubsec:pushtovospace}*, ~\ref{subsubsec:pulltovospace}*, ~\ref{subsubsec:pullfromvospace}, ~\ref{subsubsec:pushfromvospace}* \\ \hline
3602 54 & A HTTP 500 status code with an InternalFault fault in the body is thrown if the operation fails & ~\ref{subsubsec:getprotocols}, ~\ref{subsubsec:getviews}, ~\ref{subsubsec:getproperties}, ~\ref{subsubsec:createnode}, ~\ref{subsubsec:deletenode}, ~\ref{subsubsec:getnode}, ~\ref{subsubsec:setnode}, ~\ref{subsubsec:pullfromvospace} \\ \hline
3603 55 & A HTTP 400 status code with an InvalidArgument fault in the body is thrown if a specified value is invalid & ~\ref{subsubsec:setnode} \\ \hline
3604 56 & A HTTP 400 status code with an InvalidURI fault in the body is thrown if the specified URI is invalid & ~\ref{subsubsec:createnode} \\ \hline
3605 57 & A HTTP 400 status code with a TypeNotSupported fault in the body is thrown if the specified type is not supported & ~\ref{subsubsec:createnode} \\ \hline
3606 58 & A HTTP 403 status code with a PermissionDenied fault in the body is thrown if the user does not have permission to perform the operation & ~\ref{subsubsec:createnode}, ~\ref{subsubsec:deletenode}, ~\ref{subsubsec:getnode}, ~\ref{subsubsec:setnode}, ~\ref{subsubsec:pullfromvospace} \\ \hline
3607 59 & A HTTP 404 status code with a NodeNotFound fault in the body is thrown if... & ~\ref{subsubsec:movenode}, ~\ref{subsubsec:getnode}, ~\ref{subsubsec:copynode}, ~\ref{subsubsec:pullfromvospace} \\ \hline
3608 60 & A HTTP 409 status code with a DuplicateFault fault in the body is thrown if the specified node already exists & ~\ref{subsubsec:createnode} \\ \hline
3609 61 & A HTTP 404 status code with a ContainerNotFound fault in the body is thrown if a container is not found & ~\ref{subsubsec:createnode}, ~\ref{subsubsec:deletenode} \\ \hline
3610 62 & A HTTP 400 status code with a LinkFound fault in the body is thrown if a LinkNode is found & ~\ref{subsubsec:createnode}, ~\ref{subsubsec:deletenode} \\ \hline
3611 63 & The PHASE in the UWS Job representation is set to "ERROR" in case of a fault occurring & ~\ref{subsubsec:movenode}, ~\ref{subsubsec:findnodes}*, ~\ref{subsubsec:pushtovospace}*, ~\ref{subsubsec:pulltovospace}*, ~\ref{subsubsec:pullfromvospace}, ~\ref{subsubsec:pushfromvospace}* \\ \hline
3612 64 & The errorSummary element in the UWS Job representation is set to the appropriate value for the type of fault occurring & ~\ref{subsubsec:movenode}, ~\ref{subsubsec:findnodes}*, ~\ref{subsubsec:pushtovospace}*, ~\ref{subsubsec:pulltovospace}*, ~\ref{subsubsec:pullfromvospace}, ~\ref{subsubsec:pushfromvospace}* \\ \hline
3613 65 & The appropriate fault representation is provided at the error URI for the job & ~\ref{subsubsec:movenode}, ~\ref{subsubsec:findnodes}*, ~\ref{subsubsec:pushtovospace}*, ~\ref{subsubsec:pulltovospace}*, ~\ref{subsubsec:pullfromvospace}, ~\ref{subsubsec:pushfromvospace}* \\ \hline
3614 \end{tabular}
3615
3616 \section{Standard properties}
3617 \label{sec:standard properties}
3618 This table summarizes the standard properties that SHALL be recognized by a VOSpace service and are registered in the IVOA Registry of Registries.
3619
3620 \hskip-4.0cm\begin{tabular}{ | p {8cm} | p {8cm} | p {2cm} | }
3621 \hline
3622 \textbf{Property} & \textbf{Description} & \textbf{Data type} \\ \hline
3623 ivo://ivoa.net/vospace/core\#availableSpace & the amount of space available within a container & string \\ \hline
3624 ivo://ivoa.net/vospace/core\#btime & the initial creation time & string \\ \hline
3625 ivo://ivoa.net/vospace/core\#contributor & an entity responsible for making contributions to this resource & URI \\ \hline
3626 ivo://ivoa.net/vospace/core\#coverage & a spatial or temporal topic of the resource, the spatial applicability of the resource, or the jurisdiction under which the resource is relevant & string \\ \hline
3627 ivo://ivoa.net/vospace/core\#creator & an entity primarily responsible for making the resource & URI \\ \hline
3628 ivo://ivoa.net/vospace/core\#ctime & the status change (aka metadata modification) time & datetime \\ \hline
3629 ivo://ivoa.net/vospace/core\#date & a point or period of time associated with an event in the lifecycle of the resource & datetime \\ \hline
3630 ivo://ivoa.net/vospace/core\#description & an account of the resource & string \\ \hline
3631 ivo://ivoa.net/vospace/core\#format & the file format, physical medium or dimensions of the resource & string \\ \hline
3632 ivo://ivoa.net/vospace/core\#groupread & the list of groups which can only read this resource & delimiter-separated list \\ \hline
3633 ivo://ivoa.net/vospace/core\#groupwrite & the list of groups which can read and write to this resource & delimiter-separated list \\ \hline
3634 ivo://ivoa.net/vospace/core\#identifier & an unambiguous reference to the resource within a given context & string/URI \\ \hline
3635 ivo://ivoa.net/vospace/core\#language & a language of the resource & string \\ \hline
3636 ivo://ivoa.net/vospace/core\#length & the length or size of a resource & float \\ \hline
3637 ivo://ivoa.net/vospace/core\#mtime & the data modification time & datetime \\ \hline
3638 ivo://ivoa.net/vospace/core\#publicread & whether this resource is world readable & boolean \\ \hline
3639 ivo://ivoa.net/vospace/core\#publisher & an entity responsible for making the resource available & uri \\ \hline
3640 ivo://ivoa.net/vospace/core\#quota & the value of a system quota on the resource & string \\ \hline
3641 ivo://ivoa.net/vospace/core\#relation & a related resource & URI \\ \hline
3642 ivo://ivoa.net/vospace/core\#rights & information about rights held in and over the resource & string \\ \hline
3643 ivo://ivoa.net/vospace/core\#source & a related resource from which the described resource is derived & string \\ \hline
3644 ivo://ivoa.net/vospace/core\#subject & the topic of the resource & string \\ \hline
3645 ivo://ivoa.net/vospace/core\#title & a name given to the resource & string \\ \hline
3646 ivo://ivoa.net/vospace/core\#type & the nature or genre of the resource & string \\ \hline
3647 \end{tabular}
3648
3649 \section{Changes from Previous Versions}
3650 \label{sec:changes from previous versions}
3651
3652 \paragraph{From version 2.1-20140805:}
3653 \begin{itemize}
3654 \item Addition of optimized HTTP GET method of data transfer for pushToVoSpace, pullFromVoSpace
3655 \item Addition of authType to Protocol in XML schema for transfer negotiation.
3656 \item Added preliminary list of standard authType URIs
3657 \item Deprecated view=data convenience method of data transfer
3658 \item Corrections to minor XML format errors in the examples throughout the document.
3659 \end{itemize}
3660
3661 \paragraph{From version 2.00-20120824:}
3662 \begin{itemize}
3663 \item Use of Resource Idenfifier and CDP in Architecture diagram clarified.
3664 \item StandardID defined for this version.
3665 \item Various formatting issues.
3666 \item Use of HTTP 500 status code clarified.
3667 \item HTTP response codes made consistent with RFC 2616.
3668 \end{itemize}
3669
3670 \paragraph{From version 2.00-20111202:}
3671 \begin{itemize}
3672 \item Clarified use of URI fragments
3673 \item Added appendix of standard properties
3674 \item Clarified multi-value properties
3675 \item Added 404 error codes to getNode and setNode for no parent container ensuring consistent behaviour
3676 \item Adjusted pushToVoSpace and pullFromVoSpace convenience methods for self consistency and closer matching to UWS Fault formatting.
3677 \end{itemize}
3678
3679 \paragraph{From version 2.00-20110628:}
3680 \begin{itemize}
3681 \item Corrected REST binding for synchronous transfer details
3682 \item Added endpoint for synchronous job POSTs
3683 \item Added properties mtime, ctime, btime
3684 \item Changed text to describe use of StandardsRegExt for standard properties, views, capabilities, tranfer protocols
3685 \item Changed error code on ContainerNotFound and LinkFound faults
3686 \item Added correct failure response for unsupported operations
3687 \end{itemize}
3688
3689 \paragraph{From version 2.00-20101112:}
3690 \begin{itemize}
3691 \item Examples amended with correct namespaces and root elements
3692 \item "$\mathtt{\sim}$" listed as a valid URI separator character along with "!"
3693 \item Core property list added to
3694 \item Properties with multiple values clarified
3695 \item Optional operations clarified and indicated in conformance matrix
3696 \item getNode and findNode operation arguments made consistent
3697 \item Synchronous HTTP PUT method added
3698 \item createNode response changed to HTTP 200 from HTTP 201
3699 \item /{transferDetails} endpoint added
3700 \item Support for .auto made optional
3701 \end{itemize}
3702
3703 \paragraph{From version 2.00-20100323:}
3704 \begin{itemize}
3705 \item Updated UWS details: use uws:jobInfo instead of uws:parameters
3706 \item Added IVOA architecture text
3707 \item Removed text about WSDL/WADL
3708 \end{itemize}
3709
3710 \bibliography{ivoatex/ivoabib}
3711
3712
3713 \end{document}

msdemlei@ari.uni-heidelberg.de
ViewVC Help
Powered by ViewVC 1.1.26