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

Clean up documentation and add documentation on activities

Browse Source
This commit is contained in:
Jessica Tallon 2014-12-30 16:01:20 +01:00
parent 7eac1e6d6b
commit 90b78c4a28
6 changed files with 237 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

186
docs/source/api/activities.rst Normal file
View File

@ -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).

54
docs/source/api/client_register.rst → docs/source/api/authentication.rst
View File

@ -11,7 +11,13 @@
Dedication along with this software. If not, see
<http://creativecommons.org/publicdomain/zero/1.0/>.
====================
==================
API Authentication
==================
.. contents:: Sections
:local:
Registering a Client
====================
@ -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*
@ -43,11 +49,11 @@ 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::
@ -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.
@ -144,14 +148,34 @@ 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.

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

@ -13,19 +13,19 @@
.. info:: Currently only image uploading is supported.
===============
Uploading Media
===============
=====
Media
=====
To use any the APIs mentioned in this document you will required :doc:`oauth`
Uploading and posting an media requiest you to make two to three requests:
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 condenced in the future however currently this is how the
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
@ -41,7 +41,7 @@ A POST request should be made to the media upload URI submitting at least two he
* `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 similiar to::
You will get back a JSON encoded response which will look similar to::
{
"updated": "2014-01-11T09:45:48Z",
@ -139,7 +139,7 @@ and update request to the endpoint, the following attributes can be submitted:
.. note:: license attribute is mediagoblin specific, pump.io does not support this attribute
The update request should look something similiar to::
The update request should look something similar to::
{
"verb": "update",

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

@ -12,7 +12,7 @@
<http://creativecommons.org/publicdomain/zero/1.0/>.
Pump.io supports a number of different interactions that can happen against
media. Theser are commenting, liking/favoriting and (re-)sharing. Currently
media. These are commenting, liking/favoriting and (re-)sharing. Currently
MediaGoblin supports just commenting although other interactions will come at
a later date.
@ -23,7 +23,7 @@ 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 similiar to::
activity should look similar to::
{
"verb": "post",

36
docs/source/api/oauth.rst
View File

@ -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.

6
docs/source/index.rst
View File

@ -105,13 +105,13 @@ This chapter covers MediaGoblin's `Pump API
work in progress; full federation is not supported at the moment, but
media uploading works! You can use something like
`PyPump <http://pypump.org>`_
to write MediaGoblin uploadable applications.)
to write MediaGoblin applications.)
.. toctree::
:maxdepth: 1
api/client_register
api/oauth
api/authentication
api/activities
api/media
api/media_interaction