docs/source/api/objects.rst

   1 .. MediaGoblin Documentation
   2
   3    Written in 2015 by MediaGoblin contributors
   4
   5    To the extent possible under law, the author(s) have dedicated all
   6    copyright and related and neighboring rights to this software to
   7    the public domain worldwide. This software is distributed without
   8    any warranty.
   9
  10    You should have received a copy of the CC0 Public Domain
  11    Dedication along with this software. If not, see
  12    <http://creativecommons.org/publicdomain/zero/1.0/>.
  13
  14 .. info:: Currently only image uploading is supported.
  15
  16 =======
  17 Objects
  18 =======
  19
  20 Using any the APIs mentioned in this document you will required
  21 :doc:`authentication`. There are many ways to interact with objects, some of
  22 which aren't supported yet by MediaGoblin such as liking or sharing objects
  23 however you can interact with them by updating them, deleting them and
  24 commenting on them.
  25
  26 Posting Objects
  27 ---------------
  28
  29 For the most part you should be able to post objects by creating the JSON
  30 representation of the object on an activity and posting that to the user's
  31 feed (outbox). Images however are slightly different and there are more steps
  32 to it as you might imagine.
  33
  34 Using posting a comment as an example, I'll show you how to post the object
  35 to GNU MediaGoblin or pump.io. I first need to create the JSON representation
  36 of the activity with the object but without the ID, URL, published or updated
  37 timestamps or any other data the server creates. My activity comment is::
  38
  39     {
  40         "verb": "post",
  41         "object": {
  42             "objectType": "comment",
  43             "content": "This is my comment to be posted",
  44             "inReplyTo": {
  45                 "id": "https://<server>/api/image/1"
  46             }
  47         }
  48     }
  49
  50 This should be posted to the users feed (outbox) which you can find out about
  51 :doc:`activities`. You will get back the full activity containing all of
  52 attributes including ID, URLs, etc.
  53
  54 Posting Media
  55 ~~~~~~~~~~~~~
  56
  57 Posting media is a special case from posting all other objects. This is because
  58 you need to submit more than just the JSON image representation, you need to
  59 actually subject the image itself. There is also strange behavior around media
  60 postings where if you want to give the media you're posting a title or
  61 description you need to perform an update too. A full media posting in order of
  62 steps to do is as follows:
  63
  64 1) Uploads the data to the server
  65 2) Post media to feed
  66 3) Update media to have title, description, license, etc. (optional)
  67
  68 This could be condensed into a 2-step process however this would need to happen
  69 upstream. If you would like to contribute to changing this upstream there is
  70 an issue open: https://github.com/e14n/pump.io/issues/657
  71
  72 To upload media you should use the URL `/api/user/<username>/uploads`.
  73
  74 A POST request should be made to the media upload URL submitting at least two
  75 headers:
  76
  77 * `Content-Type` - This being a valid MIME type for the media.
  78 * `Content-Length` - size in bytes of the media.
  79
  80 The media data should be submitted as POST data to the image upload URL.
  81 You will get back a JSON encoded response which will look similar to::
  82
  83     {
  84         "updated": "2014-01-11T09:45:48Z",
  85         "links": {
  86             "self": {
  87                 "href": "https://<server>/image/4wiBUV1HT8GRqseyvX8m-w"
  88             }
  89         },
  90         "fullImage": {
  91             "url": "https://<server>//uploads/<username>/2014/1/11/V3cBMw.jpg",
  92             "width": 505,
  93             "height": 600
  94         },
  95         "replies": {
  96             "url": "https://<server>//api/image/4wiBUV1HT8GRqseyvX8m-w/replies"
  97         },
  98         "image": {
  99             "url": "https://<server>/uploads/<username>/2014/1/11/V3cBMw_thumb.jpg",
 100             "width": 269,
 101             "height": 320
 102         },
 103         "author": {
 104             "preferredUsername": "<username>",
 105             "displayName": "<username>",
 106             "links": {
 107                 "activity-outbox": {
 108                     "href": "https://<server>/api/user/<username>/feed"
 109                 },
 110                 "self": {
 111                     "href": "https://<server>/api/user/<username>/profile"
 112                 },
 113                 "activity-inbox": {
 114                     "href": "https://<server>/api/user/<username>/inbox"
 115                 }
 116             },
 117             "url": "https://<server>/<username>",
 118             "updated": "2013-08-14T10:01:21Z",
 119             "id": "acct:<username>@<server>",
 120             "objectType": "person"
 121         },
 122         "url": "https://<server>/<username>/image/4wiBUV1HT8GRqseyvX8m-w",
 123         "published": "2014-01-11T09:45:48Z",
 124         "id": "https://<server>/api/image/4wiBUV1HT8GRqseyvX8m-w",
 125         "objectType": "image"
 126     }
 127
 128 The main things in this response is `fullImage` which contains `url` (the URL
 129 of the original image - i.e. fullsize) and `image` which contains `url` (the URL
 130 of a thumbnail version).
 131
 132 .. warning:: Media which have been uploaded but not submitted to a feed will
 133              periodically be deleted.
 134
 135 Once you've got the image object back you will need to submit the post
 136 activity to the feed. This is exactly the same process as posting any other
 137 object described above. You create a post activity and post that to the feed
 138 (outbox) endpoint. The post activity looks like::
 139
 140     {
 141         "verb": "post",
 142         "object": {
 143             "id": "https://<server>/api/image/4wiBUV1HT8GRqseyvX8m-w",
 144             "objectType": "image"
 145         }
 146     }
 147
 148 You will get back the full activity, unlike above however if you wish to
 149 submit `displayName` (title) or `content` (description) information you need
 150 to create an update activity and post that to the feed after you have posted
 151 the image. An update activity would look like::
 152
 153     {
 154         "verb": "update",
 155         "object": {
 156             "id": "https://<server>/api/image/4wiBUV1HT8GRqseyvX8m-w",
 157             "displayName": "This is my title",
 158             "content": "This is my description",
 159             "objectType": "image"
 160         }
 161     }
 162
 163 Updating Objects
 164 ----------------
 165
 166 If you would like to edit or update an object you can do so by submitting an
 167 update activity. An update to a comment might look like::
 168
 169     {
 170         "verb": "update",
 171         "object": {
 172             "id": "https://<server>/api/comment/1",
 173             "objectType": "comment",
 174             "content": "This is my new updated comment!"
 175         }
 176     }
 177
 178 This should be posted to the feed (outbox). You will get back the full update
 179 activity in response.
 180
 181 Deleting Objects
 182 ----------------
 183
 184 Objects can be deleted by submitting a delete activity to the feed. A delete
 185 object for a comment looks like::
 186
 187     {
 188         "verb": "delete",
 189         "object": {
 190             "id": "https://<server>/api/comment/id",
 191             "objectType": "comment"
 192         }
 193     }
 194
 195 You should get the full delete activity in response.
 196
 197 .. warning::
 198     While deletion works, currently because of the way deletion is implemented
 199     deletion either via the API or the web UI causes any activities to be broken
 200     and will be skipped and inaccessible. A migration to remove the broken
 201     activities will come in a future release when soft-deletion has been
 202     implemented.
 203
 204 Posting Comments
 205 ----------------
 206
 207 Comments currently can only be on media objects, this however will change in
 208 future versions of MediaGoblin to be inline with pump.io and Activity Streams
 209 1.0 which allow comments to be on any object including comments themselves.
 210
 211 If you want to submit a comment on an object it's very easy, it's just like
 212 posting any other object except you use the `inReplyTo` attribute which
 213 specifies the object you are commenting on. The `inReplyTo` needs to contain
 214 the object or specifically the ID of it.
 215
 216 Example of comment on an image::
 217
 218     {
 219         "verb": "post",
 220         "object": {
 221             "content": "My comment here",
 222             "inReplyTo": {
 223                 "id": "https://<server>/api/image/72"
 224             }
 225         }
 226     }
 227
 228 This should be posted to a feed and you will get back the full activity object
 229 as with any other object posting.