diff options
Diffstat (limited to 'docs/source/api')
| -rw-r--r-- | docs/source/api/activities.rst | 208 | ||||
| -rw-r--r-- | docs/source/api/authentication.rst (renamed from docs/source/api/client_register.rst) | 69 | ||||
| -rw-r--r-- | docs/source/api/oauth.rst | 36 | ||||
| -rw-r--r-- | docs/source/api/objects.rst | 229 |
4 files changed, 483 insertions, 59 deletions
diff --git a/docs/source/api/activities.rst b/docs/source/api/activities.rst new file mode 100644 index 00000000..cbbd1fab --- /dev/null +++ b/docs/source/api/activities.rst @@ -0,0 +1,208 @@ +.. MediaGoblin Documentation + + Written in 2015 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/>. + +========== +Activities +========== + +.. contents:: Sections + :local: + +GNU MediaGoblin uses `Activity Streams 1.0 <http://activitystrea.ms>`_ JSON +format to represent activities or events that happen. There are several +components to Activity Streams. + +Objects +======= +These represent "things" in MediaGoblin such as types of media, comments, collections +of other objects, etc. There are attributes all objects have and some attributes which +are specific to certain objects. + +Example +------- +a representation of an image object:: + + { + "id": "https://gmg.server.tld/api/image/someidhere", + "objectType": "image", + "content": "My lovely image", + "image": { + "url": "https://gmg.server.tld/mgoblin_media/media_entries/23/some_image.jpg", + "height": 1000, + "width": 500 + }, + "author": { + "id": "acct:someone@gmg.server.tld" + } + } + +This has both attributes which are on all objects (e.g. ``objectType`` and ``id``) +and attributes which are on only images (e.g. ``image``). + +Activities +========== +This is something which happens such as: commenting on an image, uploading an image, etc. +these always have a ``verb`` which describes what kind of activity it is and they always have +an ``object`` associated with them. + +Example +------- +A activity which describes the event of posting a new image:: + + { + "id": "https://gmg.server.tld/api/activity/someidhere", + "verb": "post", + "object": { + "id": "https://gmg.server.tld/api/comment/someid", + "objectType": "comment", + "content": "What a wonderful picture you have there!", + "inReplyTo": { + "id": "https://gmg.server.tld/api/image/someidhere" + } + }, + "author": { + "id": "acct:someone@gmg.server.tld" + } + } + +Collections +=========== + +These are ordered lists which contain objects. Currently in GNU MediaGoblin they are used +to represent "albums" or collections of media however they can represent anything. They will +be used in the future to represent lists/groups of users which you can send activities to. + +Example +^^^^^^^ +A collection which contains two images:: + + { + "id": "https://gmg.server.tld/api/collection/someidhere", + "totalItems": 2, + "url": "http://gmg.server.tld/u/someone/collection/cool-album/", + "items": [ + { + "id": "https://gmg.server.tld/api/image/someidhere", + "objectType": "image", + "content": "My lovely image", + "image": { + "url": "https://gmg.server.tld/mgoblin_media/media_entries/23/some_image.jpg", + "height": 1000, + "width": 500 + }, + "author": { + "id": "acct:someone@gmg.server.tld" + } + }, + { + "id": "https://gmg.server.tld/api/image/someother", + "objectType": "image", + "content": "Another image for you", + "image": { + "url": "https://gmg.server.tld/mgoblin_media/media_entries/24/some_other_image.jpg", + "height": 1000, + "width": 500 + }, + "author": { + "id": "acct:someone@gmg.server.tld" + } + } + ] + } + +Feeds +----- + +There are several feeds which can be read and posted to as part of the API. Some +of the feeds are still a work in progress however a lot of them are present for +compatibility. + +They also support certain GET parameters which allow you to control the stream. +These are: + ++-------------+----------+----------+----------------------------------+ +| Parameter | Default | Limit | Description | ++=============+==========+==========+==================================+ +| count | 20 | 200 | Number of activities to return | ++-------------+----------+----------+----------------------------------+ +| offset | 0 | No limit | Offset of collection | ++-------------+----------+----------+----------------------------------+ + +.. warning:: + Activities are added to the beginning of collection so using count and + offset is a bad way of doing pages. + +.. important:: + Due to the way we're currently doing deletes in MediaGoblin some activities + are broken and are skipped. This means the number you specify in the count + is NOT always the number of activities returned. + + +Inbox +^^^^^ + +**Endpoint:** `/api/user/<username>/inbox` + +This feed can be read by user to see what media has been sent to them. +MediaGoblin currently doesn't have the ability to sent media to anyone +as all media is public, all media on that instance should show up in the +users inbox. + +There are also subsets of the inbox which are: + +Major +""""" +**Endpoint:** ``/api/user/<username>/inbox/major`` + +This contains all major changes such as new objects being posted. Currently +comments exist in this feed, in the future they will be moved to the minor feed. + +Minor +""""" +**Endpoint:** ``/api/user/<username>/inbox/minor`` + +This contains minor changes such as objects being updated or deleted. This feed +should have comments in it, currently they are listed under major, in the future +they will exist in this endpoint. + +Direct +"""""" +**Endpoint:** ``/api/user/<username>/inbox/direct`` + +Currently this is just a mirror of the regular inbox for compatibility with +pump.io. In the future this will contain all objects specifically addressed to +the user. + +Direct major +"""""""""""" +**Endpoint:** ``/api/user/<username>/inbox/direct/major`` + +Currently this is just a mirror of the major inbox for compatibility with +pump.io. In the future this will contain all major activities which are +specifically addressed to the user. + +Direct minor +"""""""""""" +**Endpoint:** ``/api/user/<username>/inbox/direct/minor`` + +Currently this is just a mirror of the minor inbox for compatibility with +pump.io. In the future this will contain all minor activities which are +specifically addressed to the user. + +Feed (outbox) +^^^^^^^^^^^^^ +**Endpoint:** ``/api/user/<username>/feed`` + +This is where the client should post new activities. It can be read by the +user to see what they have posted. This will only contain content they have +authored or shared (sharing will come in the future). diff --git a/docs/source/api/client_register.rst b/docs/source/api/authentication.rst index 08f92c47..2db4a7bd 100644 --- a/docs/source/api/client_register.rst +++ b/docs/source/api/authentication.rst @@ -1,6 +1,6 @@ .. MediaGoblin Documentation - Written in 2011, 2012 by MediaGoblin contributors + Written in 2015 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 @@ -11,11 +11,17 @@ Dedication along with this software. If not, see <http://creativecommons.org/publicdomain/zero/1.0/>. -==================== +================== +API Authentication +================== + +.. contents:: Sections + :local: + Registering a Client ==================== -To use the GNU MediaGoblin API you need to use the dynamic client registration. This has been adapted from the `OpenID specification <https://openid.net/specs/openid-connect-registration-1_0.html>`_, this is the only part of OpenID that is being used to serve the purpose to provide the client registration which is used in OAuth. +To use the GNU MediaGoblin API you need to use the dynamic client registration. This has been adapted from the `OpenID specification <https://openid.net/specs/openid-connect-registration-1_0.html>`_, this is the only part of OpenID that is being used to serve the purpose to provide the client registration which is used in OAuth. The endpoint is ``/api/client/register`` @@ -31,7 +37,7 @@ client_secret **update only** - This should only be used updating client information, this is the client_secret given when you register contacts - **optional** - This a space seporated list of email addresses to contact of people responsible for the client + **optional** - This a space separated list of email addresses to contact of people responsible for the client application_type **required** - This is the type of client you are making, this must be either *web* or *native* @@ -39,15 +45,15 @@ application_type application_name **optional** - This is the name of your client -logo_url - **optional** - This is a URL of the logo image for your client +logo_uri + **optional** - This is a URI of the logo image for your client redirect_uri - **optional** - This is a space seporated list of pre-registered URLs for use at the Authorization Server + **optional** - This is a space separated list of pre-registered URLs for use at the Authentication Server Response --------- +^^^^^^^^ You will get back a response: @@ -60,12 +66,11 @@ client_secret expires_at This is time that the client credentials expire. If this is 0 the client registration does not expire. -======= -Example -======= +Examples +-------- Register Client ---------------- +^^^^^^^^^^^^^^^ To register a client for the first time, this is the minimum you must supply:: @@ -84,7 +89,7 @@ A Response will look like:: Updating Client ---------------- +^^^^^^^^^^^^^^^ Using the response we got above we can update the information and add new information we may have opted not to supply:: @@ -93,8 +98,8 @@ Using the response we got above we can update the information and add new inform "client_id": "vwljdhUMhhNbdKizpjZlxv", "client_secret": "hJtfhaQzgKerlLVdaeRAgmbcstSOBLRfgOinMxBCHcb", "application_type": "web", - "application_name": "MyClient!", - "logo_url": "https://myclient.org/images/my_logo.png", + "application_name": "MyClient!", + "logo_uri": "https://myclient.org/images/my_logo.png", "contacts": "myemail@someprovider.com another_developer@provider.net", } @@ -107,9 +112,8 @@ The response will just return back the client_id and client_secret you sent:: } -====== -Errors -====== +Possible Registration Errors +---------------------------- There are a number of errors you could get back, This explains what could cause some of them: @@ -129,7 +133,7 @@ client_id is required to update. When you try and update you need to specify the client_id, this will be what you were given when you initially registered the client. client_secret is required to update. - When you try to update you need to specify the client_secrer, this will be what you were given when you initially register the client. + When you try to update you need to specify the client_secret, this will be what you were given when you initially register the client. Unauthorized. This is when you are trying to update however the client_id and/or client_secret you have submitted are incorrect. @@ -140,19 +144,38 @@ Only set client_id for update. Only set client_secret for update. This should only be given when you update. -Logo URL <url> is not a valid URL +Logo URL <URL> is not a valid URL This is when the URL specified did not meet the validation. contacts must be a string of space-separated email addresses. - ``contacts`` should be a string (not a list), ensure each email is seporated by a space + ``contacts`` should be a string (not a list), ensure each email is separated by a space Email <email> is not a valid email This is when you have submitted an invalid email address redirect_uris must be space-separated URLs. - ``redirect_uris`` should be a string (not a list), ensure each URL is seporated by a space + ``redirect_uris`` should be a string (not a list), ensure each URL is separated by a space URI <URI> is not a valid URI This is when your URI is invalid. - +OAuth +===== + +GNU MediaGoblin uses OAuth1 to authenticate requests to the API. There are many +libraries out there for OAuth1, you're likely not going to have to do much. There +is a library for the GNU MediaGoblin called `PyPump <https://github.com/xray7224/PyPump>`_. +We are not using OAuth2 as we want to stay completely compatible with pump.io. + + +Endpoints +--------- + +These are the endpoints you need to use for the OAuth requests: + +`/oauth/request_token` is for getting the request token. + +`/oauth/authorize` is to send the user to to authorize your application. + +`/oauth/access_token` is for getting the access token to use in requests. + diff --git a/docs/source/api/oauth.rst b/docs/source/api/oauth.rst deleted file mode 100644 index 003ad492..00000000 --- a/docs/source/api/oauth.rst +++ /dev/null @@ -1,36 +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 - <http://creativecommons.org/publicdomain/zero/1.0/>. - -============== -Authentication -============== - -GNU MediaGoblin uses OAuth1 to authenticate requests to the API. There are many -libraries out there for OAuth1, you're likely not going to have to do much. There -is a library for the GNU MediaGoblin called `PyPump <https://github.com/xray7224/PyPump>`_. -We are not using OAuth2 as we want to stay completely compatable with GNU MediaGoblin. - - -We use :doc:`client_register` to get the client ID and secret. - -Endpoints ---------- - -These are the endpoints you need to use for the oauth requests: - -`/oauth/request_token` is for getting the request token. - -`/oauth/authorize` is to send the user to to authorize your application. - -`/oauth/access_token` is for getting the access token to use in requests. - diff --git a/docs/source/api/objects.rst b/docs/source/api/objects.rst new file mode 100644 index 00000000..854febe1 --- /dev/null +++ b/docs/source/api/objects.rst @@ -0,0 +1,229 @@ +.. MediaGoblin Documentation + + Written in 2015 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. + +======= +Objects +======= + +Using any the APIs mentioned in this document you will required +:doc:`authentication`. There are many ways to interact with objects, some of +which aren't supported yet by MediaGoblin such as liking or sharing objects +however you can interact with them by updating them, deleting them and +commenting on them. + +Posting Objects +--------------- + +For the most part you should be able to post objects by creating the JSON +representation of the object on an activity and posting that to the user's +feed (outbox). Images however are slightly different and there are more steps +to it as you might imagine. + +Using posting a comment as an example, I'll show you how to post the object +to GNU MediaGoblin or pump.io. I first need to create the JSON representation +of the activity with the object but without the ID, URL, published or updated +timestamps or any other data the server creates. My activity comment is:: + + { + "verb": "post", + "object": { + "objectType": "comment", + "content": "This is my comment to be posted", + "inReplyTo": { + "id": "https://<server>/api/image/1" + } + } + } + +This should be posted to the users feed (outbox) which you can find out about +:doc:`activities`. You will get back the full activity containing all of +attributes including ID, URLs, etc. + +Posting Media +~~~~~~~~~~~~~ + +Posting media is a special case from posting all other objects. This is because +you need to submit more than just the JSON image representation, you need to +actually subject the image itself. There is also strange behavior around media +postings where if you want to give the media you're posting a title or +description you need to perform an update too. A full media posting in order of +steps to do is as follows: + +1) Uploads the data to the server +2) Post media to feed +3) Update media to have title, description, license, etc. (optional) + +This could be condensed into a 2-step process however this would need to happen +upstream. If you would like to contribute to changing this upstream there is +an issue open: https://github.com/e14n/pump.io/issues/657 + +To upload media you should use the URL `/api/user/<username>/uploads`. + +A POST request should be made to the media upload URL submitting at least two +headers: + +* `Content-Type` - This being a valid MIME type for the media. +* `Content-Length` - size in bytes of the media. + +The media data should be submitted as POST data to the image upload URL. +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. + +Once you've got the image object back you will need to submit the post +activity to the feed. This is exactly the same process as posting any other +object described above. You create a post activity and post that to the feed +(outbox) endpoint. The post activity looks like:: + + { + "verb": "post", + "object": { + "id": "https://<server>/api/image/4wiBUV1HT8GRqseyvX8m-w", + "objectType": "image" + } + } + +You will get back the full activity, unlike above however if you wish to +submit `displayName` (title) or `content` (description) information you need +to create an update activity and post that to the feed after you have posted +the image. An update activity would look like:: + + { + "verb": "update", + "object": { + "id": "https://<server>/api/image/4wiBUV1HT8GRqseyvX8m-w", + "displayName": "This is my title", + "content": "This is my description", + "objectType": "image" + } + } + +Updating Objects +---------------- + +If you would like to edit or update an object you can do so by submitting an +update activity. An update to a comment might look like:: + + { + "verb": "update", + "object": { + "id": "https://<server>/api/comment/1", + "objectType": "comment", + "content": "This is my new updated comment!" + } + } + +This should be posted to the feed (outbox). You will get back the full update +activity in response. + +Deleting Objects +---------------- + +Objects can be deleted by submitting a delete activity to the feed. A delete +object for a comment looks like:: + + { + "verb": "delete", + "object": { + "id": "https://<server>/api/comment/id", + "objectType": "comment" + } + } + +You should get the full delete activity in response. + +.. warning:: + While deletion works, currently because of the way deletion is implemented + deletion either via the API or the web UI causes any activities to be broken + and will be skipped and inaccessible. A migration to remove the broken + activities will come in a future release when soft-deletion has been + implemented. + +Posting Comments +---------------- + +Comments currently can only be on media objects, this however will change in +future versions of MediaGoblin to be inline with pump.io and Activity Streams +1.0 which allow comments to be on any object including comments themselves. + +If you want to submit a comment on an object it's very easy, it's just like +posting any other object except you use the `inReplyTo` attribute which +specifies the object you are commenting on. The `inReplyTo` needs to contain +the object or specifically the ID of it. + +Example of comment on an image:: + + { + "verb": "post", + "object": { + "content": "My comment here", + "inReplyTo": { + "id": "https://<server>/api/image/72" + } + } + } + +This should be posted to a feed and you will get back the full activity object +as with any other object posting. |