heckyel/mediagoblin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update and reorganise API documentation

Browse Source
This commit is contained in:
Jessica Tallon 2015-01-09 14:02:49 +00:00
parent 2663394688
commit 2a702d0180
5 changed files with 267 additions and 237 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
docs/source/api/activities.rst
View File

@ -23,13 +23,13 @@ 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::
{
@ -50,13 +50,13 @@ 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::
{
@ -76,7 +76,8 @@ A activity which describes the event of posting a new image::
}
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.
@ -120,14 +121,35 @@ A collection which contains two images::
}
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 activities to return |
+-------------+----------+----------+----------------------------------+
| offset | 0 | No limit | Offset of collection |
+-------------+----------+----------+----------------------------------+
.. warning::
Activities are added to the beginning of collection so using count and
offset to do 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`
@ -139,14 +161,14 @@ 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
@ -154,7 +176,7 @@ 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
@ -162,7 +184,7 @@ 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
@ -170,7 +192,7 @@ 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
@ -178,7 +200,7 @@ 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

155
docs/source/api/media.rst
View File

@ -1,155 +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/>.
.. 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.

65
docs/source/api/media_interaction.rst
View File

@ -1,65 +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/>.
Pump.io supports a number of different interactions that can happen against
media. These 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 similar to::
{
"verb": "post",
"object": {
"objectType": "comment",
"inReplyTo": <media>
}
}
This is where `<media>` 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": <author user object>
},
{
"id": 4,
"objectType": "comment",
"content": "Another comment! Blimey!",
"author": <author user object>
}
],
"url": "http://some.server/api/images/1/comments/"
}

229
docs/source/api/objects.rst Normal file
View File

@ -0,0 +1,229 @@
.. 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.
=======
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 behavour around media
postings where if you want to give the media you're posting a title or
description you need to peform 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 condenced 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 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 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 back, unlike above however if you with 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 back 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 webUI causes any activities to be broken
and will be skipped and unaccessable. 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.

3
docs/source/index.rst
View File

@ -112,8 +112,7 @@ to write MediaGoblin applications.)
api/authentication
api/activities
api/media
api/media_interaction
api/objects