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

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