Content Upload inconsistencies...
Laurent-Walter Goix
i have run through the "trunk" core API spec (and Shindig's PHP code)
to check content upload mechanisms.
i know there is some ongoing discussion about CMIS, but in general it
would be useful to fix the current upload procedure(s) in an
implementable/workable way. To be precise, spec and reference
implementations are now truly inconsistent. my apologies in advance
for this long post but a global cleanup is probably needed here.
the core API spec, section 4, mentions 3 alternatives for uploading
media:
1- two steps: 2 requests: picture, then mediaItem object
2- shortcut: 1 request: picture as body and media item attributes as
request parameters
3- multipart: 1 request: form-data style with mediaItem object and
picture in separate fields
wrt 1, the example request line (POST /album/112233?mediaType=IMAGE
HTTP/1.1) is not consistent with any URI fragment of the Album service
specification in social API server (typically "/albums/" User-Id "/
@self"), nor conceptually with the idea of posting to the album
service to actually post a content (semantically pertinent to the
mediaItem service)
in 2, a similar (wrong) request line is given (POST /album/112233/
mediaitem/?title=Lena&type=IMAGE HTTP/1.1). the type/mediaType
parameter name is also confusing
in 3, an RPC-style mechanism is mentioned, which is reasonable
although it does not specifically refer to the RPC protocol part of
the spec. neither on the other way around section 2.2 of the core api
spec mentions form-data as a possible content-type for this specific
use case. there is no further assumption on how to discover (e.g. from
a gadget) whether this mechanism is supported or not by the server/
container and how to post media (if supported). finally, on the
implementation side shindig does not seem to support form-data on the
rpc endpoint (i can understand this is up to developers)
when looking instead at the mediaItem spec in social api spec (which
seems to be the right place formally), section 2.6.2 suggest to use
POST "/mediaItem/" User-Id "/@self/" Album-Id to create a mediaItem
(without the content itself). the spec mentions "mediaItem" in the uri-
fragment for the POST, whilst all other fragments use
"mediaItems" (plural).
what is interesting is that from the implementation side (still
shindig), there is truly one mechanism supported at this stage for
content upload, which is a mix between this latter spec and
alternative 2 of the content upload section. indeed after some tests
we got POST /mediaitems/112233/@self/1?title=Lena&type=IMAGE HTTP/1.1
working using shindig3, and inserting the raw image as body.
probably the implementation actually got it more right than the spec
itself, and would deserve to be clarified 1) in section 2.6.2 of the
social api spec to formally define this option of media embedding, 2)
in section 4.2 of the core api spec to refer to a correct example.
regarding the other 2 alternative mechanisms, depending on the various
interests, alternative 3 (form-data) may be formally clarified as an
option by adding (optional) support for form-data content-type in the
rpc section 2.2 of the core api spec, whilst alternative 1 would
probably need some more in-depth revision.
i got this from live experience in writing clients to post content to
shindig, but i assume that the spec cleanup would also benefit whoever
is willing to implement such capability in a standard way in an
opensocial-compliant server.
i am available to help if needed with the revision text but would like
to get some comments especially from users who may have already
experienced/implemented content upload with opensocial.
cheers
walter
Laurent-Walter Goix
i am resuming this thread as i am now checking the possibility of
performing content upload using the rest api endpoint. in particular i
would be interested in a mechanism similar to the "multipart" method
indicated in section 4.3 of the Core API spec, but updated to 1)
activitystreams instead of old-fashioned activity, 2) rest instead of
rpc.
for 1) the example indicated uses a "@field." shortcut in the url
property (string) of the mediaItem object to cross-reference the other
field of the multipart request. when mapping to activitystreams, the
mediaitem becomes an object and formally the "url" property must be an
absolute IRI...So from the spec point of point a non-compliance is
introduced. i checked other properties from the formal definition of a
object re activitystreams but couldn't find a suitable one.
for 2) i am thinking at a solution reusing the createActivity path
(POST /activitystreams/@me/@self ) that can be distinguished from the
"traditional" activity creation (uploading an activity object as
application/json content type) by posting a multipart containing both
the activity object + a file to be uploaded. this would highly
optimize the upload of pictures when checking in for example or
similar use cases.
i would like to get your view on these 2 issues to come up with a
"standard" way for uploading content using the latest (rest) api...
thanks
walter
On Dec 13 2011, 5:09 pm, Laurent-Walter Goix
Evgeny Bogdanov
Laurent-Walter Goix
i do not have JS examples that make use of these proposals, but here
are some POST examples of both alternatives for your comments from the
spec perspective:
1- post as mediaitem
POST /mediaItems/bob/@self/pictures?title=Lena&type=IMAGE HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: image/jpeg
Content-Length: <image length>
<jpeg binary data>
HTTP/1.1 201 Created
Date: Tue, 29 Nov 2011 12:00:00 GMT
Location: http://example.com/mediaItems/bob/@self/pictures/11223344
Content-Length: 209
Content-Type: application/json
{
"id" : "http://example.com/media/11223344",
"url": "http://example.com/bob/media/pictures/11223344.jpg",
"thumbnail_url": "http://example.com/bob/media/pictures/
thumb_11223344.jpg",
"mime_type": "image/jpeg",
"type": "image"
}
2.post as activity (as anticipated the use of "@field" in the "url"
parameter of the activity object is non standard...)
POST /activitystreams/bob/@self HTTP/1.1
Host: example.com
Accept: application/json
Content-type: multipart/form-data; boundary=--abcdef012345xyZ
Content-length: <contentLength>
--abcdef012345xyZ
Content-Disposition: form-data; name="json"
{
"actor": {
"id": "example.com:bob"
},
"object": {
"objectType": "image",
"url": "@field:newImage",
"location": {
"position": "+48.52+002.20/"
}
},
"title": "Partying from my favorite Club!",
"target": {
"objectType": "place",
"id": "http: //example.com/places/5647"
},
"verb": "post"
}
------------abcdef012345xyZ
Content-Disposition: form-data; name="image1"
Content-Type: image/jpeg
<jpeg image data>
------------abcdef012345xyZ--
HTTP/1.1 201 Created
Date: Tue, 29 Nov 2011 12:00:00 GMT
Location: http://example.com/activitystreams/bob/@self/1234
Content-Length: 580
Content-Type: application/json
{
"id": "http://example.com/activities/1234",
"published": "2012-01-10T15:04:55Z",
"actor": {
"id": "example.com:bob"
},
"object": {
"objectType": "image",
"id": "http://example.com/media/1234",
"url": " http://example.com/bob/media/default/1234.jpg",
"location": {
"position": "+48.52+002.20/"
}
},
"title": "Partying from my favorite Club!",
"target": {
"objectType": "place",
"id": "http: //example.com/places/5647"
},
"verb": "post"
}
i would welcome JS examples on how to achieve this using the osapi
library (or other).
walter