Comments and suggestions on the VOSpace-2.1 working draft.

From the mailing list announcement :

• Summary of recent changes
• Line by line diff

General

HTML anchors

The HTML anchors use name rather than id, is this intentional ?

    <a name="0.1_sec1">1. Introduction</a>

rather than

    <a id="0.1_sec1">1. Introduction</a>

Section 1.1

Create node path

In the create node operation described in section 1.1, the path encoded in the URL of the HTTP PUT request

    http://nvo.caltech.edu/vospace/myData/table123

does not match the path in the message content

    vos://nvo.caltech!vospace/mytable1

In addition, the URL of the HTTP PUT request does not point to a location within the {service}/nodes tree defined in the specification

If the endpoint for the VOSpace service is

    http://nvo.caltech.edu/vospace/

then the target URL for the HTTP PUT request should be

    http://nvo.caltech.edu/vospace/nodes/myData/table123

and the uri in the node XML should either be blank, or it should match the path in the HTTP PUT target URL

    vos://nvo.caltech!vospace/myData/table123

Create node text

There are a number of places where the description of the create operation could be clarified.

In the original VOSpace-1.x SOAP service, the create message contained the target URI as part of the message body.

The VOSpace-2.x REST service create message is essentially the same XML message content, but the request is sent to a location inside the {service}/nodes tree with target node path embeded in the URL.

    {service}/nodes/{path}

This means the node path is encoded in two different places within the same message.

• The current specification does not clearly state how the intended node path should be included in the target URL of the HTTP PUT request.
• The current specification does not clearly state whether or not the node uri should be included in the content of the create node message.
• The current specification does not clearly state whether or not the service should return an error if the path in the uri in the message content does not match the path in the target URL of the HTTP PUT request

Push transfer endpoint

In the description of the data transfer in section 1.1, the endpoint URL for the HTTP POST appears to point to a location relative to the target node

    http://nvo.caltech.edu/vospace/myData/table123/transfers

In VOSpace-2.x transfer operations should be initiated by a HTTP POST to a separate UWS {service}/transfers endpoint, outside the {service}/nodes tree.

If the endpoint for the VOSpace service is

    http://nvo.caltech.edu/vospace/

then the endpoint URL for initiating a transfer should be

    http://nvo.caltech.edu/vospace/transfers

Push transfer target

The path of the target in the body of the HTTP POST message should match the path of the node created in the first step of the example

    <transfer xmlns="http://www.ivoa.net/xml/VOSpace/v2.1">
        ....
        <target>vos://nvo.caltech!vospace/myData/table123</target>
        ....
    </transfer>

Push transfer protocol

The content for the transfer request given in the example uses a non-standard protocol URI

    <transfer ...>
        ....
        <protocol uri="ivo://ivoa.net/vospace/core#http-put"/>  
        ....
    </transfer>

The standard protocol URI for HTTP PUT transfers listed in section 3.5.3 of the same document is

    ivo://ivoa.net/vospace/core#httpput

Push transfer redirect

The description of the data transfer in section 1.1, misses out a step in the sequence of requests.

Following the initial HTTP POST to the {service}/transfers endpoint, the current text implies that the server responds with the HTTP PUT destination directly in the response.

"The service will reply with the URL that the user will HTTP PUT the data file"

This omits the details of the 303 redirect response

    HTTP/1.1 303 See Other
    ....
    Location: http://nvo.caltech.edu/vospace/transfers/581

Which directs the client to a representation of the UWS job, which contains the HTTP PUT destination that the client should send the data to

    <uws:job ....>
        <uws:jobId>581</uws:jobId>
        ....
        <uws:jobInfo>
            <vos:transfer>
                ....
                <vos:protocol uri="ivo://ivoa.net/vospace/core#http-put">
                    <vos:endpoint>http://d21.caltech.edu/temp/d558</vos:endpoint>
                </vos:protocol>
                ....
            </vos:transfer>
        <uws:jobInfo>
        ....
    </uws:job>

In addition, the example URL for the HTTP PUT destination,

    http://nvo.caltech.edu/bvospace/myData/table123/transfers/147516ab

appears to point to a location relative to the target node.

It would be clearer if the example used a URL that did not overlap with the VOSpace service endpoint in any way

    http://d21.caltech.edu/temp/d558

Pull transfer endpoint

The endpoint URL for the HTTP POST should point to the global {service}/transfers endpoint, not to what appears to be a location relative to the target node within the node tree.

If the endpoint for the VOSpace service is

    http://nvo.caltech.edu/vospace/

then the target URL to initate a transfer should be

    http://nvo.caltech.edu/vospace/transfers

Pull transfer target

The path of the target in the body of the HTTP POST message should match the path of the node created in the first step of the example.

    <transfer xmlns="http://www.ivoa.net/xml/VOSpace/v2.1">
        ....
        <target>vos://nvo.caltech!vospace/myData/table123</target>
        ....
    </transfer>

Pull transfer redirect

The current text implies that the server responds directly with the HTTP GET source URL that the client should use to fetch the data from.

This omits the details of the 303 redirect response

    HTTP/1.1 303 See Other
    ....
    Location: http://nvo.caltech.edu/vospace/transfers/581

which directs the client to a representation of the UWS job, which contains the HTTP GET location that client can fetch the data from.

In addition, the example URL for the HTTP GET location to transfer the data

    http://nvo.caltech.edu/bvospace/myData/table123/transfers/147516ab

appears to point to a location relative to the target node within the {service}/node tree.

It would be clearer if the example used a URL that did not overlap with the VOSpace service endpoint in any way.

    http://d22.caltech.edu/temp/e612