Improve the documentation

docs/source/api/images.rst

@@ -15,27 +15,120 @@
 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`.
 
-+-------------+-----------+---------------------+--------------------+
+A POST request should be made to the image upload URI submitting at least two header:
-| 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       |
-+-------------+-----------+---------------------+--------------------+
 
-*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).