Update and reorganise API documentation
This commit is contained in:
Jessica Tallon
@@ -1,12 +1,12 @@
|
||||
.. 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/>.
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user