.. 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
.
==========
Activities
==========
.. contents:: Sections
:local:
GNU MediaGoblin uses `Activity Streams 1.0 `_ 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//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//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//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//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//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//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//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).