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

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