aboutsummaryrefslogtreecommitdiffstats
path: root/docs/source/api/activities.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/api/activities.rst')
-rw-r--r--docs/source/api/activities.rst186
1 files changed, 186 insertions, 0 deletions
diff --git a/docs/source/api/activities.rst b/docs/source/api/activities.rst
new file mode 100644
index 00000000..bd1b4152
--- /dev/null
+++ b/docs/source/api/activities.rst
@@ -0,0 +1,186 @@
+.. 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/>.
+
+==========
+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.
+
+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).