Update and reorganise API documentation
This commit is contained in:
parent
2663394688
commit
2a702d0180
@ -23,13 +23,13 @@ format to represent activities or events that happen. There are several
|
|||||||
components to Activity Streams.
|
components to Activity Streams.
|
||||||
|
|
||||||
Objects
|
Objects
|
||||||
-------
|
=======
|
||||||
These represent "things" in MediaGoblin such as types of media, comments, collections
|
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
|
of other objects, etc. There are attributes all objects have and some attributes which
|
||||||
are specific to certain objects.
|
are specific to certain objects.
|
||||||
|
|
||||||
Example
|
Example
|
||||||
^^^^^^^
|
-------
|
||||||
a representation of an image object::
|
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``).
|
and attributes which are on only images (e.g. ``image``).
|
||||||
|
|
||||||
Activities
|
Activities
|
||||||
----------
|
==========
|
||||||
This is something which happens such as: commenting on an image, uploading an image, etc.
|
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
|
these always have a ``verb`` which describes what kind of activity it is and they always have
|
||||||
an ``object`` associated with them.
|
an ``object`` associated with them.
|
||||||
|
|
||||||
Example
|
Example
|
||||||
^^^^^^^
|
-------
|
||||||
A activity which describes the event of posting a new image::
|
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
|
Collections
|
||||||
-----------
|
===========
|
||||||
|
|
||||||
These are ordered lists which contain objects. Currently in GNU MediaGoblin they are used
|
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
|
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.
|
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
|
Feeds
|
||||||
=====
|
-----
|
||||||
|
|
||||||
There are several feeds which can be read and posted to as part of the API. Some
|
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
|
of the feeds are still a work in progress however a lot of them are present for
|
||||||
compatibility.
|
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
|
Inbox
|
||||||
-----
|
^^^^^
|
||||||
|
|
||||||
**Endpoint:** `/api/user/<username>/inbox`
|
**Endpoint:** `/api/user/<username>/inbox`
|
||||||
|
|
||||||
@ -139,14 +161,14 @@ users inbox.
|
|||||||
There are also subsets of the inbox which are:
|
There are also subsets of the inbox which are:
|
||||||
|
|
||||||
Major
|
Major
|
||||||
^^^^^
|
"""""
|
||||||
**Endpoint:** ``/api/user/<username>/inbox/major``
|
**Endpoint:** ``/api/user/<username>/inbox/major``
|
||||||
|
|
||||||
This contains all major changes such as new objects being posted. Currently
|
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.
|
comments exist in this feed, in the future they will be moved to the minor feed.
|
||||||
|
|
||||||
Minor
|
Minor
|
||||||
^^^^^
|
"""""
|
||||||
**Endpoint:** ``/api/user/<username>/inbox/minor``
|
**Endpoint:** ``/api/user/<username>/inbox/minor``
|
||||||
|
|
||||||
This contains minor changes such as objects being updated or deleted. This feed
|
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.
|
they will exist in this endpoint.
|
||||||
|
|
||||||
Direct
|
Direct
|
||||||
^^^^^^
|
""""""
|
||||||
**Endpoint:** ``/api/user/<username>/inbox/direct``
|
**Endpoint:** ``/api/user/<username>/inbox/direct``
|
||||||
|
|
||||||
Currently this is just a mirror of the regular inbox for compatibility with
|
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.
|
the user.
|
||||||
|
|
||||||
Direct major
|
Direct major
|
||||||
^^^^^^^^^^^^
|
""""""""""""
|
||||||
**Endpoint:** ``/api/user/<username>/inbox/direct/major``
|
**Endpoint:** ``/api/user/<username>/inbox/direct/major``
|
||||||
|
|
||||||
Currently this is just a mirror of the major inbox for compatibility with
|
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.
|
specifically addressed to the user.
|
||||||
|
|
||||||
Direct minor
|
Direct minor
|
||||||
^^^^^^^^^^^^
|
""""""""""""
|
||||||
**Endpoint:** ``/api/user/<username>/inbox/direct/minor``
|
**Endpoint:** ``/api/user/<username>/inbox/direct/minor``
|
||||||
|
|
||||||
Currently this is just a mirror of the minor inbox for compatibility with
|
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.
|
specifically addressed to the user.
|
||||||
|
|
||||||
Feed (outbox)
|
Feed (outbox)
|
||||||
-------------
|
^^^^^^^^^^^^^
|
||||||
**Endpoint:** ``/api/user/<username>/feed``
|
**Endpoint:** ``/api/user/<username>/feed``
|
||||||
|
|
||||||
This is where the client should post new activities. It can be read by the
|
This is where the client should post new activities. It can be read by the
|
||||||
|
@ -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.
|
|
||||||
|
|
||||||
=====
|
|
||||||
Media
|
|
||||||
=====
|
|
||||||
|
|
||||||
To use any the APIs mentioned in this document you will required :doc:`oauth`
|
|
||||||
|
|
||||||
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 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
|
|
||||||
|
|
||||||
----------------------
|
|
||||||
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 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.
|
|
||||||
|
|
||||||
--------------
|
|
||||||
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 similar 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.
|
|
@ -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. These 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 similar 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/"
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
229
docs/source/api/objects.rst
Normal file
229
docs/source/api/objects.rst
Normal file
@ -0,0 +1,229 @@
|
|||||||
|
.. 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.
|
||||||
|
|
||||||
|
=======
|
||||||
|
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 condenced 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 back, unlike above however if you with 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 back 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 unaccessable. 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.
|
@ -112,8 +112,7 @@ to write MediaGoblin applications.)
|
|||||||
|
|
||||||
api/authentication
|
api/authentication
|
||||||
api/activities
|
api/activities
|
||||||
api/media
|
api/objects
|
||||||
api/media_interaction
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Loading…
x
Reference in New Issue
Block a user