156 lines
5.5 KiB
ReStructuredText
156 lines
5.5 KiB
ReStructuredText
.. 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.
|
|
|
|
=====
|
|
Media
|
|
=====
|
|
|
|
To use any the APIs mentioned in this document you will required :doc:`oauth`
|
|
|
|
Uploading and posting an media request 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 recondensed 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 similar 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 similar 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.
|