Uploading an Image
==================
-You must have fully authenticated with oauth to upload an image.
+To use any the APIs mentioned in this document you will required :doc:`oauth`
-The endpoint is: ``/api/user/<username>/uploads/`` (POST endpoint)
+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.
-There are four GET parameters available to use, if they're not specified the defaults (listed below) will be used, the parameters are:
+To upload an image you should use the URI `/api/user/<username>/uploads`.
-+-------------+-----------+---------------------+--------------------+
-| Parameter | Required | Default | Example |
-+=============+===========+=====================+====================+
-| qqfile | No | unknown | my_picture.jpg |
-+-------------+-----------+---------------------+--------------------+
-| title | No | <qqfile> | My Picture! |
-+-------------+-----------+---------------------+--------------------+
-| description | No | None | My awesome picture |
-+-------------+-----------+---------------------+--------------------+
-| licence | No | All rights reserved | CC BY-SA 3.0 |
-+-------------+-----------+---------------------+--------------------+
+A POST request should be made to the image upload URI submitting at least two header:
-*Note: licence is not part of the pump.io spec and is a GNU MediaGoblin specific parameter*
+* `Content-Type` - This being a valid mimetype for the image.
+* `Content-Length` - size in bytes of the image.
-Example URL (with parameters): /api/user/tsyesika/uploads/?qqfile=river.jpg&title=The%20River&description=The%20river%20that%20I%20use%20to%20visit%20as%20a%20child%20licence=CC%20BY-SA%203.0
+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::
-Submit the binary image data in the POST parameter.
+ {
+ "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).
+
+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/<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 image). The request should look
+something like::
+
+ {
+ "verb": "post",
+ "object": {
+ "id": "https://<server>/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://<server>/api/image/6_K9m-2NQFi37je845c83w",
+ "objectType": "image"
+ }
+ }
+
+(Again, any other data submitted **will** be ignored).
projects / mediagoblin.git / commitdiff