Re: Binary resource and metadata example (ISSUE-15)

On Mon, May 27, 2013 at 5:17 PM, Nandana Mihindukulasooriya <
nmihindu@fi.upm.es> wrote:

> Hi,
>
> ISSUE-15 [1] was resolved in the F2F2 with the following resolution. I am
> trying to exemplify it.
>
> [[
> Assuming the existing qualifications that POST is optional, and supporting
> "binary" media types is optional: The expected response to a post for
> create that creates a non-LDPR is a 201, with location header whose URI I
> identifies the resource whose representation matches the POST input, and
> the response SHOULD include a Link header rel="meta" href= another URI P
> identifying the resource whose state is the server-managed properties. The
> URIs I and P MAY be distinct, but this is not required. When the object of
> a membership triple (I) is DELETEd, the server MUST automatically deletes
> any related resource P that it created previously.
> ]]
>
> A question and some comments. (Any feedback on the example is very welcome)
>
> * Do we have to say that the GET operation (ex-3) of the binary resource
> should also include to the Link header (similar to the created response) ?
>
Seems like a good idea.


>  * In the F2F, we discussed about discouraging the deletion of P
> (metadata LDPR) but we didn't come to a conclusion. May be it also need to
> be taken into consideration in the spec edits.
>
I think leaving to spec edits makes sense.


> * One common use case is that we want to POST the binary resource and
> metadata about it (title / description of an image etc.) together like we
> do with some REST apis using Content-Type: multipart/form-data
> [2]. However, in the current approach we can achieve the same with two
> steps, first POSTing the resource and then updating the metadata LDPR
> (ex-6) so this is not a big problem.
>
Agree with 2 step is fine, as typical case I've found is that client wants
to pick the name.  Title and description are somewhat rare cases and can be
handled via 2nd GET/PUT.


>
> Here is the example,
>
> ex-1). We have an LDPC which we can use to create binary resources
>
> ---------------
> GET /Bug1/attachments/ HTTP/1.1
> Host: example.org
> Accept: text/turtle
> ------
> HTTP/1.1 200 OK
> Content-Type: text/turtle
> ETag: W/"123456789"
>
> </Bug1/attachments/> a ldp:Container .
> ---------------
>
> ex-2). We POST the binary resource to the LDPC and it responds with a
> Location header and a Link header.
>
> ---------------
> POST /Bug1/attachments/ HTTP/1.1
> Host: example.org
> Content-Type: image/png
> Slug: login-page.png
> Content-Length: 1254
>
> #### binary data #####
> ------
> HTTP/1.1 201 Created
> Location: /Bug1/attachments/login-page.png
> Link: </Bug1/attachments/attachment1>; rel="meta"
> Content-Length: 0
> ---------------
>
> ex-3). We can access the created resource using the URI in the location
> header.
>
> ---------------
> GET /Bug1/attachments/login-page.png
> Host: example.org
> Accept: image/png
> ------
> HTTP/1.1 200 OK
> Content-Type: text/turtle
> Link: </Bug1/attachments/attachment1>; rel="meta"
> ETag: W/"123456789"
>
> #### binary data #####
> ---------------
>
> ex-4). We can access the metadata about the resource using the URI in the
> Link header.
>
> ---------------
> GET /Bug1/at[1] -
> https://dev.twitter.com/docs/api/1.1/post/statuses/update_with_mediatachments/attachment1
> Host: example.org
> Accept: text/turtle
> ------
> HTTP/1.1 200 OK
> Content-Type: text/turtle
> ETag: W/"123456789"
>
> </Bug1/attachments/attachment1> x:content
> </Bug1/attachments/login-page.png> ;
>  </Bug1/attachments/login-page.png> ;
>       dct:create[1] -
> https://dev.twitter.com/docs/api/1.1/post/statuses/update_with_mediad"2013-05-27T17:05Z"^^xsd:dateTime ;
>       dct:creator </user/jhondoe#me> .
> ---------------
>
> ex-5). The container is updated to with the binary resource as a member.
>
> ---------------
> GET /Bug1/attachments/ HTTP/1.1
> Host: exampl[1] -
> https://dev.twitter.com/docs/api/1.1/post/statuses/update_with_mediae.org<http://example.org>
> Accept: text/turtle
> ------
> HTTP/1.1 200 OK
> Content-Type: text/turtle
> ETag: W/"123456789"
>
> </Bug1/attachments/> a ldp:Container ;
>        rdfs:member </Bug1/login-page.png> .
> ---------------
>
> ex-6). We can update the metadata about the binary resource using the
> metadata URI
>
> ---------------
> PUT /Bug1/attachments/attachment1 HTTP/1.1
> Host: example.org
> Content-Type: text/turtle
> If-Match: W/"123456789"
>
> </Bug1/attachments/attachment1> x:content
> </Bug1/attachments/login-page.png> ;
> </Bug1/attachments/login-page.png> ;
>       *dc:title "Screenshop of the Web UI of the login page when error
> happened";*
>       dct:created "2013-05-27T17:05Z"^^xsd:dateTime ;
>       dct:creator </user/jhondoe#me> .
> ------
> HTTP/1.1 204 No Content
> ETag: W/"123456790"
>  ---------------
>
> ex-7). We can delete the binary resource and the metadata LDPR must be
> automatically deleted.
>
> ---------------
>  DELETE /Bug1/attachments/login-page.png HTTP/1.1
>  Host: example.org
> ------
>  HTTP/1.1 204 No Content
>  ETag: W/"123456790"
>  ---------------
>
> Then if we retrieve
>
> ---------------
> GET /Bug1/attachments/login-page.png HTTP/1.1
>  Host: example.org
>  ------
>  HTTP/1.1 410 Gone
> ---------------
>
> and
>
> ---------------
>  GET /Bug1/attachments/attachment1 HTTP/1.1
>  Host: example.org
> ------
>  HTTP/1.1 410 Gone
> ---------------
>
> Best Regards,
> Nandana
>
> [1] - http://www.w3.org/2012/ldp/track/issues/15
> [2] - https://dev.twitter.com/docs/api/1.1/post/statuses/update_with_media
>

Examples look right to me, we also said we could endorse a predicate to use
in the "meta" resource to highlight the relationship <
http://www.w3.org/2007/05/powder-s#describedBy> [3]
These example look like what we did for OSLC-CM exploration of this usage
as well [4]

[3] - http://www.w3.org/2007/powder/powder-errata#describedby
[4] -
http://open-services.net/wiki/change-management/Attachments-for-Change-Requests/

-- 
- Steve