From 247a3b788f3deea120c3f272eda7f7ce9ff54764 Mon Sep 17 00:00:00 2001 From: xray7224 Date: Thu, 14 Nov 2013 22:42:07 +0000 Subject: Adds the unit-tests for API and cleans up API --- docs/source/api/images.rst | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 docs/source/api/images.rst (limited to 'docs/source/api') diff --git a/docs/source/api/images.rst b/docs/source/api/images.rst new file mode 100644 index 00000000..6e4d3d48 --- /dev/null +++ b/docs/source/api/images.rst @@ -0,0 +1,41 @@ +.. 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 + . + +================== +Uploading an Image +================== + +You must have fully authenticated with oauth to upload an image. + +The endpoint is: ``/api/user//uploads/`` (POST endpoint) + +There are four GET parameters available to use, if they're not specified the defaults (listed below) will be used, the parameters are: + ++-------------+-----------+---------------------+--------------------+ +| Parameter | Required | Default | Example | ++=============+===========+=====================+====================+ +| qqfile | No | unknown | my_picture.jpg | ++-------------+-----------+---------------------+--------------------+ +| title | No | | 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* + +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 + +Submit the binary image data in the POST parameter. + -- cgit v1.2.3 From 3d869e82b0d6ebe6a1a2f991a9efb76458704095 Mon Sep 17 00:00:00 2001 From: xray7224 Date: Sun, 12 Jan 2014 18:19:37 +0000 Subject: Improve the documentation --- docs/source/api/images.rst | 127 +++++++++++++++++++++++++++++++++++++++------ 1 file changed, 110 insertions(+), 17 deletions(-) (limited to 'docs/source/api') diff --git a/docs/source/api/images.rst b/docs/source/api/images.rst index 6e4d3d48..8c2653d4 100644 --- a/docs/source/api/images.rst +++ b/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//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//uploads`. -+-------------+-----------+---------------------+--------------------+ -| Parameter | Required | Default | Example | -+=============+===========+=====================+====================+ -| qqfile | No | unknown | my_picture.jpg | -+-------------+-----------+---------------------+--------------------+ -| title | No | | 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:///image/4wiBUV1HT8GRqseyvX8m-w" + } + }, + "fullImage": { + "url": "https:////uploads//2014/1/11/V3cBMw.jpg", + "width": 505, + "height": 600 + }, + "replies": { + "url": "https:////api/image/4wiBUV1HT8GRqseyvX8m-w/replies" + }, + "image": { + "url": "https:///uploads//2014/1/11/V3cBMw_thumb.jpg", + "width": 269, + "height": 320 + }, + "author": { + "preferredUsername": "", + "displayName": "", + "links": { + "activity-outbox": { + "href": "https:///api/user//feed" + }, + "self": { + "href": "https:///api/user//profile" + }, + "activity-inbox": { + "href": "https:///api/user//inbox" + } + }, + "url": "https:///", + "updated": "2013-08-14T10:01:21Z", + "id": "acct:@", + "objectType": "person" + }, + "url": "https:////image/4wiBUV1HT8GRqseyvX8m-w", + "published": "2014-01-11T09:45:48Z", + "id": "https:///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//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:///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:///api/image/6_K9m-2NQFi37je845c83w", + "objectType": "image" + } + } + +(Again, any other data submitted **will** be ignored). -- cgit v1.2.3 From 128af9533ffa60c356a187d0f98c370f65876893 Mon Sep 17 00:00:00 2001 From: Jessica Tallon Date: Tue, 8 Jul 2014 17:27:38 +0100 Subject: Update documentation on uploading media via API --- docs/source/api/images.rst | 134 --------------------------------------- docs/source/api/media.rst | 155 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 155 insertions(+), 134 deletions(-) delete mode 100644 docs/source/api/images.rst create mode 100644 docs/source/api/media.rst (limited to 'docs/source/api') diff --git a/docs/source/api/images.rst b/docs/source/api/images.rst deleted file mode 100644 index 8c2653d4..00000000 --- a/docs/source/api/images.rst +++ /dev/null @@ -1,134 +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 - . - -================== -Uploading an Image -================== - -To use any the APIs mentioned in this document you will required :doc:`oauth` - -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. - -To upload an image you should use the URI `/api/user//uploads`. - -A POST request should be made to the image upload URI submitting at least two header: - -* `Content-Type` - This being a valid mimetype for the image. -* `Content-Length` - size in bytes of the image. - -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:: - - { - "updated": "2014-01-11T09:45:48Z", - "links": { - "self": { - "href": "https:///image/4wiBUV1HT8GRqseyvX8m-w" - } - }, - "fullImage": { - "url": "https:////uploads//2014/1/11/V3cBMw.jpg", - "width": 505, - "height": 600 - }, - "replies": { - "url": "https:////api/image/4wiBUV1HT8GRqseyvX8m-w/replies" - }, - "image": { - "url": "https:///uploads//2014/1/11/V3cBMw_thumb.jpg", - "width": 269, - "height": 320 - }, - "author": { - "preferredUsername": "", - "displayName": "", - "links": { - "activity-outbox": { - "href": "https:///api/user//feed" - }, - "self": { - "href": "https:///api/user//profile" - }, - "activity-inbox": { - "href": "https:///api/user//inbox" - } - }, - "url": "https:///", - "updated": "2013-08-14T10:01:21Z", - "id": "acct:@", - "objectType": "person" - }, - "url": "https:////image/4wiBUV1HT8GRqseyvX8m-w", - "published": "2014-01-11T09:45:48Z", - "id": "https:///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//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:///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:///api/image/6_K9m-2NQFi37je845c83w", - "objectType": "image" - } - } - -(Again, any other data submitted **will** be ignored). diff --git a/docs/source/api/media.rst b/docs/source/api/media.rst new file mode 100644 index 00000000..bafe43d3 --- /dev/null +++ b/docs/source/api/media.rst @@ -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 + . + +.. 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//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:///image/4wiBUV1HT8GRqseyvX8m-w" + } + }, + "fullImage": { + "url": "https:////uploads//2014/1/11/V3cBMw.jpg", + "width": 505, + "height": 600 + }, + "replies": { + "url": "https:////api/image/4wiBUV1HT8GRqseyvX8m-w/replies" + }, + "image": { + "url": "https:///uploads//2014/1/11/V3cBMw_thumb.jpg", + "width": 269, + "height": 320 + }, + "author": { + "preferredUsername": "", + "displayName": "", + "links": { + "activity-outbox": { + "href": "https:///api/user//feed" + }, + "self": { + "href": "https:///api/user//profile" + }, + "activity-inbox": { + "href": "https:///api/user//inbox" + } + }, + "url": "https:///", + "updated": "2013-08-14T10:01:21Z", + "id": "acct:@", + "objectType": "person" + }, + "url": "https:////image/4wiBUV1HT8GRqseyvX8m-w", + "published": "2014-01-11T09:45:48Z", + "id": "https:///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//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:///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:///api/image/6_K9m-2NQFi37je845c83w", + "objectType": "image" + } + } + +.. warning:: Any other data submitted **will** be ignored. -- cgit v1.2.3 From 161cf125f06ae6e0f7f1f1b719ce708dbc70ab4c Mon Sep 17 00:00:00 2001 From: Jessica Tallon Date: Sat, 12 Jul 2014 09:04:40 +0100 Subject: Add documentation for interacting with media entires --- docs/source/api/media_interaction.rst | 65 +++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 docs/source/api/media_interaction.rst (limited to 'docs/source/api') diff --git a/docs/source/api/media_interaction.rst b/docs/source/api/media_interaction.rst new file mode 100644 index 00000000..41114a71 --- /dev/null +++ b/docs/source/api/media_interaction.rst @@ -0,0 +1,65 @@ +.. 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 + . + +Pump.io supports a number of different interactions that can happen against +media. Theser are commenting, liking/favoriting and (re-)sharing. Currently +MediaGoblin supports just commenting although other interactions will come at +a later date. + +-------------- +How to comment +-------------- + +.. warning:: Commenting on a comment currently is NOT supported. + +Commenting is done by posting a comment activity to the users feed. The +activity should look similiar to:: + + { + "verb": "post", + "object": { + "objectType": "comment", + "inReplyTo": + } + } + +This is where `` is the media object you have got with from the server. + +---------------- +Getting comments +---------------- + +The media object you get back should have a `replies` section. This should +be an object which contains the number of replies and if there are any (i.e. +number of replies > 0) then `items` will include an array of every item:: + + { + "totalItems": 2, + "items: [ + { + "id": 1, + "objectType": "comment", + "content": "I'm a comment ^_^", + "author": + }, + { + "id": 4, + "objectType": "comment", + "content": "Another comment! Blimey!", + "author": + } + ], + "url": "http://some.server/api/images/1/comments/" + } + + -- cgit v1.2.3