From 128af9533ffa60c356a187d0f98c370f65876893 Mon Sep 17 00:00:00 2001 From: Jessica Tallon Date: Tue, 8 Jul 2014 17:27:38 +0100 Subject: Update documentation on uploading media via API --- docs/source/api/images.rst | 134 --------------------------------------- docs/source/api/media.rst | 155 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 155 insertions(+), 134 deletions(-) delete mode 100644 docs/source/api/images.rst create mode 100644 docs/source/api/media.rst (limited to 'docs/source/api') diff --git a/docs/source/api/images.rst b/docs/source/api/images.rst deleted file mode 100644 index 8c2653d4..00000000 --- a/docs/source/api/images.rst +++ /dev/null @@ -1,134 +0,0 @@ -.. MediaGoblin Documentation - - Written in 2011, 2012 by MediaGoblin contributors - - To the extent possible under law, the author(s) have dedicated all - copyright and related and neighboring rights to this software to - the public domain worldwide. This software is distributed without - any warranty. - - You should have received a copy of the CC0 Public Domain - Dedication along with this software. If not, see - . - -================== -Uploading an Image -================== - -To use any the APIs mentioned in this document you will required :doc:`oauth` - -Uploading and posting an image requiest you to make two requests, one of which -submits the image to the server, the other of which will post the meta data. - -To upload an image you should use the URI `/api/user//uploads`. - -A POST request should be made to the image upload URI submitting at least two header: - -* `Content-Type` - This being a valid mimetype for the image. -* `Content-Length` - size in bytes of the image. - -The binary image data should be submitted as POST data to the image upload URI. -You will get back a JSON encoded response which will look similiar to:: - - { - "updated": "2014-01-11T09:45:48Z", - "links": { - "self": { - "href": "https:///image/4wiBUV1HT8GRqseyvX8m-w" - } - }, - "fullImage": { - "url": "https:////uploads//2014/1/11/V3cBMw.jpg", - "width": 505, - "height": 600 - }, - "replies": { - "url": "https:////api/image/4wiBUV1HT8GRqseyvX8m-w/replies" - }, - "image": { - "url": "https:///uploads//2014/1/11/V3cBMw_thumb.jpg", - "width": 269, - "height": 320 - }, - "author": { - "preferredUsername": "", - "displayName": "", - "links": { - "activity-outbox": { - "href": "https:///api/user//feed" - }, - "self": { - "href": "https:///api/user//profile" - }, - "activity-inbox": { - "href": "https:///api/user//inbox" - } - }, - "url": "https:///", - "updated": "2013-08-14T10:01:21Z", - "id": "acct:@", - "objectType": "person" - }, - "url": "https:////image/4wiBUV1HT8GRqseyvX8m-w", - "published": "2014-01-11T09:45:48Z", - "id": "https:///api/image/4wiBUV1HT8GRqseyvX8m-w", - "objectType": "image" - } - -The main things in this response is `fullImage` which contains `url` (the URL -of the original image - i.e. fullsize) and `image` which contains `url` (the URL -of a thumbnail version). - -Submit to feed -============== - -The next request you will probably wish to make is to post the image to your -feed, this currently in GNU MediaGoblin will just show it visably on the website. -In the future it will allow you to specify whom should see this image. - -The URL you will want to make a POST request to to is `/api/user//feed` - -You first should do a post to the feed URI with some of the information you got -back from the above request (which uploaded the image). The request should look -something like:: - - { - "verb": "post", - "object": { - "id": "https:///api/image/6_K9m-2NQFi37je845c83w", - "objectType": "image" - } - } - -(Any other data submitted **will** be ignored) - -Finally if you wish to set a title, description and licence you will need to do -and update request to the endpoint, the following attributes can be submitted: - -+--------------+---------------------------------------+-------------------+ -| Name | Description | Required/Optional | -+==============+=======================================+===================+ -| displayName | This is the title for the image | Optional | -+--------------+---------------------------------------+-------------------+ -| content | This is the description for the image | Optional | -+--------------+---------------------------------------+-------------------+ -| license | This is the licence to be used | Optional | -+--------------+---------------------------------------+-------------------+ - -.. note:: license attribute is mediagoblin specific, pump.io does not support this attribute - - -The update request should look something similiar to:: - - { - "verb": "update", - "object": { - "displayName": "My super awesome image!", - "content": "The awesome image I took while backpacking to modor", - "license": "creativecommons.org/licenses/by-sa/3.0/", - "id": "https:///api/image/6_K9m-2NQFi37je845c83w", - "objectType": "image" - } - } - -(Again, any other data submitted **will** be ignored). diff --git a/docs/source/api/media.rst b/docs/source/api/media.rst new file mode 100644 index 00000000..bafe43d3 --- /dev/null +++ b/docs/source/api/media.rst @@ -0,0 +1,155 @@ +.. MediaGoblin Documentation + + Written in 2011, 2012 by MediaGoblin contributors + + To the extent possible under law, the author(s) have dedicated all + copyright and related and neighboring rights to this software to + the public domain worldwide. This software is distributed without + any warranty. + + You should have received a copy of the CC0 Public Domain + Dedication along with this software. If not, see + . + +.. info:: Currently only image uploading is supported. + +=============== +Uploading Media +=============== + +To use any the APIs mentioned in this document you will required :doc:`oauth` + +Uploading and posting an media requiest you to make two to three requests: + +1) Uploads the data to the server +2) Post media to feed +3) Update media to have title, description, license, etc. (optional) + +These steps could be condenced in the future however currently this is how the +pump.io API works. There is currently an issue open, if you would like to change +how this works please contribute upstream: https://github.com/e14n/pump.io/issues/657 + +---------------------- +Upload Media to Server +---------------------- + +To upload media you should use the URI `/api/user//uploads`. + +A POST request should be made to the media upload URI submitting at least two header: + +* `Content-Type` - This being a valid mimetype for the media. +* `Content-Length` - size in bytes of the media. + +The media data should be submitted as POST data to the image upload URI. +You will get back a JSON encoded response which will look similiar to:: + + { + "updated": "2014-01-11T09:45:48Z", + "links": { + "self": { + "href": "https:///image/4wiBUV1HT8GRqseyvX8m-w" + } + }, + "fullImage": { + "url": "https:////uploads//2014/1/11/V3cBMw.jpg", + "width": 505, + "height": 600 + }, + "replies": { + "url": "https:////api/image/4wiBUV1HT8GRqseyvX8m-w/replies" + }, + "image": { + "url": "https:///uploads//2014/1/11/V3cBMw_thumb.jpg", + "width": 269, + "height": 320 + }, + "author": { + "preferredUsername": "", + "displayName": "", + "links": { + "activity-outbox": { + "href": "https:///api/user//feed" + }, + "self": { + "href": "https:///api/user//profile" + }, + "activity-inbox": { + "href": "https:///api/user//inbox" + } + }, + "url": "https:///", + "updated": "2013-08-14T10:01:21Z", + "id": "acct:@", + "objectType": "person" + }, + "url": "https:////image/4wiBUV1HT8GRqseyvX8m-w", + "published": "2014-01-11T09:45:48Z", + "id": "https:///api/image/4wiBUV1HT8GRqseyvX8m-w", + "objectType": "image" + } + +The main things in this response is `fullImage` which contains `url` (the URL +of the original image - i.e. fullsize) and `image` which contains `url` (the URL +of a thumbnail version). + +.. warning:: Media which have been uploaded but not submitted to a feed will + periodically be deleted. + +-------------- +Submit to feed +-------------- + +This is submitting the media to appear on the website. This will create an +object in your feed which will then appear on the GNU MediaGoblin website so the +user and others can view and interact with the media. + +The URL you need to POST to is `/api/user//feed` + +You first should do a post to the feed URI with some of the information you got +back from the above request (which uploaded the media). The request should look +something like:: + + { + "verb": "post", + "object": { + "id": "https:///api/image/6_K9m-2NQFi37je845c83w", + "objectType": "image" + } + } + +.. warning:: Any other data submitted **will** be ignored + +------------------- +Submitting Metadata +------------------- + +Finally if you wish to set a title, description and license you will need to do +and update request to the endpoint, the following attributes can be submitted: + ++--------------+---------------------------------------+-------------------+ +| Name | Description | Required/Optional | ++==============+=======================================+===================+ +| displayName | This is the title for the media | Optional | ++--------------+---------------------------------------+-------------------+ +| content | This is the description for the media | Optional | ++--------------+---------------------------------------+-------------------+ +| license | This is the license to be used | Optional | ++--------------+---------------------------------------+-------------------+ + +.. note:: license attribute is mediagoblin specific, pump.io does not support this attribute + + +The update request should look something similiar to:: + + { + "verb": "update", + "object": { + "displayName": "My super awesome image!", + "content": "The awesome image I took while backpacking to modor", + "license": "creativecommons.org/licenses/by-sa/3.0/", + "id": "https:///api/image/6_K9m-2NQFi37je845c83w", + "objectType": "image" + } + } + +.. warning:: Any other data submitted **will** be ignored. -- cgit v1.2.3