diff options
Diffstat (limited to 'docs/source/api/media.rst')
| -rw-r--r-- | docs/source/api/media.rst | 155 |
1 files changed, 0 insertions, 155 deletions
diff --git a/docs/source/api/media.rst b/docs/source/api/media.rst deleted file mode 100644 index bafe43d3..00000000 --- a/docs/source/api/media.rst +++ /dev/null @@ -1,155 +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 - <http://creativecommons.org/publicdomain/zero/1.0/>. - -.. 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/<username>/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://<server>/image/4wiBUV1HT8GRqseyvX8m-w" - } - }, - "fullImage": { - "url": "https://<server>//uploads/<username>/2014/1/11/V3cBMw.jpg", - "width": 505, - "height": 600 - }, - "replies": { - "url": "https://<server>//api/image/4wiBUV1HT8GRqseyvX8m-w/replies" - }, - "image": { - "url": "https://<server>/uploads/<username>/2014/1/11/V3cBMw_thumb.jpg", - "width": 269, - "height": 320 - }, - "author": { - "preferredUsername": "<username>", - "displayName": "<username>", - "links": { - "activity-outbox": { - "href": "https://<server>/api/user/<username>/feed" - }, - "self": { - "href": "https://<server>/api/user/<username>/profile" - }, - "activity-inbox": { - "href": "https://<server>/api/user/<username>/inbox" - } - }, - "url": "https://<server>/<username>", - "updated": "2013-08-14T10:01:21Z", - "id": "acct:<username>@<server>", - "objectType": "person" - }, - "url": "https://<server>/<username>/image/4wiBUV1HT8GRqseyvX8m-w", - "published": "2014-01-11T09:45:48Z", - "id": "https://<server>/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/<username>/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://<server>/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://<server>/api/image/6_K9m-2NQFi37je845c83w", - "objectType": "image" - } - } - -.. warning:: Any other data submitted **will** be ignored. |