diff options
Diffstat (limited to 'docs/source')
| -rw-r--r-- | docs/source/api/activities.rst | 208 | ||||
| -rw-r--r-- | docs/source/api/authentication.rst (renamed from docs/source/api/client_register.rst) | 67 | ||||
| -rw-r--r-- | docs/source/api/media.rst | 155 | ||||
| -rw-r--r-- | docs/source/api/media_interaction.rst | 65 | ||||
| -rw-r--r-- | docs/source/api/oauth.rst | 36 | ||||
| -rw-r--r-- | docs/source/api/objects.rst | 229 | ||||
| -rw-r--r-- | docs/source/conf.py | 4 | ||||
| -rw-r--r-- | docs/source/index.rst | 9 | ||||
| -rw-r--r-- | docs/source/plugindocs/oauth.rst | 1 | ||||
| -rw-r--r-- | docs/source/siteadmin/configuration.rst | 28 | ||||
| -rw-r--r-- | docs/source/siteadmin/deploying.rst | 36 | ||||
| -rw-r--r-- | docs/source/siteadmin/media-types.rst | 19 | ||||
| -rw-r--r-- | docs/source/siteadmin/relnotes.rst | 2 |
13 files changed, 548 insertions, 311 deletions
diff --git a/docs/source/api/activities.rst b/docs/source/api/activities.rst new file mode 100644 index 00000000..cbbd1fab --- /dev/null +++ b/docs/source/api/activities.rst @@ -0,0 +1,208 @@ +.. 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 + <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. + +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/<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). diff --git a/docs/source/api/client_register.rst b/docs/source/api/authentication.rst index 08f92c47..1d52d300 100644 --- a/docs/source/api/client_register.rst +++ b/docs/source/api/authentication.rst @@ -1,6 +1,6 @@ .. MediaGoblin Documentation - Written in 2011, 2012 by MediaGoblin contributors + 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 @@ -11,11 +11,17 @@ Dedication along with this software. If not, see <http://creativecommons.org/publicdomain/zero/1.0/>. -==================== +================== +API Authentication +================== + +.. contents:: Sections + :local: + Registering a Client ==================== -To use the GNU MediaGoblin API you need to use the dynamic client registration. This has been adapted from the `OpenID specification <https://openid.net/specs/openid-connect-registration-1_0.html>`_, this is the only part of OpenID that is being used to serve the purpose to provide the client registration which is used in OAuth. +To use the GNU MediaGoblin API you need to use the dynamic client registration. This has been adapted from the `OpenID specification <https://openid.net/specs/openid-connect-registration-1_0.html>`_, this is the only part of OpenID that is being used to serve the purpose to provide the client registration which is used in OAuth. The endpoint is ``/api/client/register`` @@ -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* @@ -39,15 +45,15 @@ application_type application_name **optional** - This is the name of your client -logo_url - **optional** - This is a URL of the logo image for your client +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:: @@ -93,8 +98,8 @@ Using the response we got above we can update the information and add new inform "client_id": "vwljdhUMhhNbdKizpjZlxv", "client_secret": "hJtfhaQzgKerlLVdaeRAgmbcstSOBLRfgOinMxBCHcb", "application_type": "web", - "application_name": "MyClient!", - "logo_url": "https://myclient.org/images/my_logo.png", + "application_name": "MyClient!", + "logo_uri": "https://myclient.org/images/my_logo.png", "contacts": "myemail@someprovider.com another_developer@provider.net", } @@ -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,15 +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. + diff --git a/docs/source/api/media.rst b/docs/source/api/media.rst deleted file mode 100644 index bafe43d3..00000000 --- a/docs/source/api/media.rst +++ /dev/null @@ -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. - -=============== -Uploading 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: - -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 -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 similiar 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 similiar 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. diff --git a/docs/source/api/media_interaction.rst b/docs/source/api/media_interaction.rst deleted file mode 100644 index 41114a71..00000000 --- a/docs/source/api/media_interaction.rst +++ /dev/null @@ -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. Theser 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 similiar 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/" - } - - diff --git a/docs/source/api/oauth.rst b/docs/source/api/oauth.rst deleted file mode 100644 index 003ad492..00000000 --- a/docs/source/api/oauth.rst +++ /dev/null @@ -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. - diff --git a/docs/source/api/objects.rst b/docs/source/api/objects.rst new file mode 100644 index 00000000..4c199616 --- /dev/null +++ b/docs/source/api/objects.rst @@ -0,0 +1,229 @@ +.. 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 + <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 condensed 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, unlike above however if you wish 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 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 unaccessible. 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. diff --git a/docs/source/conf.py b/docs/source/conf.py index 0b2bccac..0f53e4cf 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -219,7 +219,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('index', 'gnumediagoblin', u'GNU MediaGoblin Documentation', + ('index', 'mediagoblin', u'GNU MediaGoblin Documentation', [u'Chris Webber, et al'], 1) ] @@ -233,7 +233,7 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - ('index', 'gnumediagoblin', u'GNU MediaGoblin Documentation', u'gnumediagoblin', + ('index', 'mediagoblin', u'GNU MediaGoblin Documentation', u'mediagoblin', 'GNU MediaGoblin', 'Media sharing web application.', 'Miscellaneous'), ] diff --git a/docs/source/index.rst b/docs/source/index.rst index 8e49d1d1..a4fd2455 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -105,15 +105,14 @@ 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/media - api/media_interaction + api/authentication + api/activities + api/objects diff --git a/docs/source/plugindocs/oauth.rst b/docs/source/plugindocs/oauth.rst deleted file mode 100644 index 0685c9d1..00000000 --- a/docs/source/plugindocs/oauth.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../mediagoblin/plugins/oauth/README.rst diff --git a/docs/source/siteadmin/configuration.rst b/docs/source/siteadmin/configuration.rst index 3da5cdd9..dd0d6cd9 100644 --- a/docs/source/siteadmin/configuration.rst +++ b/docs/source/siteadmin/configuration.rst @@ -109,6 +109,34 @@ they sound like. - email_smtp_user - email_smtp_pass +Changing data directory +----------------------- + +MediaGoblin by default stores your data in wherever ``data_basedir``. +This can be changed by changing the value in your ``mediagoblin.ini`` file +for example:: + + [DEFAULT] + data_basedir = "/var/mediagoblin/user_data" + +For efficiency reasons MediaGoblin doesn't serve these files itself and +instead leaves that to the webserver. You will have to alter the location +to match the path in ``data_basedir``. + +If you use ``lazyserver.sh`` you need to change the ``paste.ini`` file:: + + [app:mediagoblin] + /mgoblin_media = /var/mediagoblin/user_data + +If you use nginx you need to change the config:: + + # Instance specific media: + location /mgoblin_media/ { + alias /var/mediagoblin/user_data; + } + +Once you have done this you will need to move any existing media you had in the +old directory to the new directory so existing media still can be displayed. All other configuration changes ------------------------------- diff --git a/docs/source/siteadmin/deploying.rst b/docs/source/siteadmin/deploying.rst index 350f91ec..af36728c 100644 --- a/docs/source/siteadmin/deploying.rst +++ b/docs/source/siteadmin/deploying.rst @@ -45,7 +45,7 @@ Dependencies MediaGoblin has the following core dependencies: -- Python 2.6 or 2.7 +- Python 2.7 - `python-lxml <http://lxml.de/>`_ - `git <http://git-scm.com/>`_ - `SQLite <http://www.sqlite.org/>`_/`PostgreSQL <http://www.postgresql.org/>`_ @@ -193,26 +193,14 @@ Change to the MediaGoblin directory that you just created:: Clone the MediaGoblin repository and set up the git submodules:: - git clone https://gitorious.org/mediagoblin/mediagoblin.git + git clone https://gitorious.org/mediagoblin/mediagoblin.git -b stable cd mediagoblin git submodule init && git submodule update -And set up the in-package virtualenv:: +Set up the hacking environment:: - (virtualenv --python=python2 --system-site-packages . || virtualenv --python=python2 .) && ./bin/python setup.py develop - -.. note:: - - We presently have an **experimental** make-style deployment system. if - you'd like to try it, instead of the above command, you can run:: - - ./experimental-bootstrap.sh && ./configure && make - - This also includes a number of nice features, such as keeping your - viratualenv up to date by simply running `make update`. - - Note: this is liable to break. Use this method with caution. + ./bootstrap.sh && ./configure && make The above provides an in-package install of ``virtualenv``. While this is counter to the conventional ``virtualenv`` configuration, it is @@ -384,6 +372,18 @@ this ``nginx.conf`` file should be modeled on the following:: } } +The first four ``location`` directives instruct Nginx to serve the +static and uploaded files directly rather than through the MediaGoblin +process. This approach is faster and requires less memory. + +.. note:: + + The user who owns the Nginx process, normally ``www-data``, + requires execute permission on the directories ``static``, + ``public``, ``theme_static`` and ``plugin_static`` plus all their + parent directories. This user also requires read permission on all + the files within these directories. This is normally the default. + Now, nginx instance is configured to serve the MediaGoblin application. Perform a quick test to ensure that this configuration works. Restart nginx so it picks up your changes, with a command that @@ -429,3 +429,7 @@ Security Considerations and restart the server, so that it creates a new secret key. All previous sessions will be invalidated. +.. + Local variables: + fill-column: 70 + End: diff --git a/docs/source/siteadmin/media-types.rst b/docs/source/siteadmin/media-types.rst index f8030081..7d9f72b0 100644 --- a/docs/source/siteadmin/media-types.rst +++ b/docs/source/siteadmin/media-types.rst @@ -79,12 +79,15 @@ good/bad/ugly). On Debianoid systems .. code-block:: bash - sudo apt-get install python-gst0.10 \ - gstreamer0.10-plugins-base \ - gstreamer0.10-plugins-bad \ - gstreamer0.10-plugins-good \ - gstreamer0.10-plugins-ugly \ - gstreamer0.10-ffmpeg + sudo apt-get install python-gi python3-gi \ + gstreamer1.0-tools \ + gir1.2-gstreamer-1.0 \ + gir1.2-gst-plugins-base-1.0 \ + gstreamer1.0-plugins-good \ + gstreamer1.0-plugins-ugly \ + gstreamer1.0-plugins-bad \ + gstreamer1.0-libav \ + python-gst-1.0 Add ``[[mediagoblin.media_types.video]]`` under the ``[plugins]`` section in @@ -206,7 +209,7 @@ It may work on some earlier versions, but that is not guaranteed (and is surely not to work prior to Blender 2.5X). Add ``[[mediagoblin.media_types.stl]]`` under the ``[plugins]`` section in your -``mediagoblin_local.ini`` and restart MediaGoblin. +``mediagoblin_local.ini`` and restart MediaGoblin. Run @@ -255,7 +258,7 @@ This feature has been tested on Fedora with: It may work on some earlier versions, but that is not guaranteed. Add ``[[mediagoblin.media_types.pdf]]`` under the ``[plugins]`` section in your -``mediagoblin_local.ini`` and restart MediaGoblin. +``mediagoblin_local.ini`` and restart MediaGoblin. Run diff --git a/docs/source/siteadmin/relnotes.rst b/docs/source/siteadmin/relnotes.rst index 16899a0b..91c11eec 100644 --- a/docs/source/siteadmin/relnotes.rst +++ b/docs/source/siteadmin/relnotes.rst @@ -69,7 +69,7 @@ That's it, probably! If you run into problems, don't hesitate to - Removed a false download link from setup.py 0.7.0 -==== +===== **Do this to upgrade** |