Update documentation on uploading media via API
This commit is contained in:
Jessica Tallon
155
docs/source/api/media.rst
Normal file
155
docs/source/api/media.rst
Normal file
@@ -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
|
||||
<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.
|
||||
Reference in New Issue
Block a user