docs/src/contributing_apub_api_outline.md

   1 # Activitypub API outline
   2
   3 - Start with the [reddit API](https://www.reddit.com/dev/api), and find [Activitypub vocab](https://www.w3.org/TR/activitystreams-vocabulary/) to match it.
   4
   5 <!-- toc -->
   6
   7 - [Actors](#actors)
   8   * [User / Person](#user--person)
   9   * [Community / Group](#community--group)
  10 - [Objects](#objects)
  11   * [Post / Page](#post--page)
  12   * [Post Listings / Ordered CollectionPage](#post-listings--ordered-collectionpage)
  13   * [Comment / Note](#comment--note)
  14   * [Comment Listings / Ordered CollectionPage](#comment-listings--ordered-collectionpage)
  15   * [Deleted thing / Tombstone](#deleted-thing--tombstone)
  16 - [Actions](#actions)
  17   * [Comments](#comments)
  18     + [Create](#create)
  19     + [Delete](#delete)
  20     + [Update](#update)
  21     + [Read](#read)
  22     + [Like](#like)
  23     + [Dislike](#dislike)
  24   * [Posts](#posts)
  25     + [Create](#create-1)
  26     + [Delete](#delete-1)
  27     + [Update](#update-1)
  28     + [Read](#read-1)
  29   * [Communities](#communities)
  30     + [Create](#create-2)
  31     + [Delete](#delete-2)
  32     + [Update](#update-2)
  33     + [Join](#join)
  34     + [Leave](#leave)
  35   * [Moderator](#moderator)
  36     + [Ban user from community / Block](#ban-user-from-community--block)
  37     + [Delete Comment](#delete-comment)
  38     + [Invite a moderator](#invite-a-moderator)
  39     + [Accept Invitation](#accept-invitation)
  40     + [Reject Invitation](#reject-invitation)
  41
  42 <!-- tocstop -->
  43
  44 ## Actors
  45
  46 ### [User / Person](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-person)
  47 ```
  48 {
  49   "@context": "https://www.w3.org/ns/activitystreams",
  50   "type": "Person",
  51   "id": "https://instance_url/api/v1/user/sally_smith",
  52   "inbox": "https://instance_url/api/v1/user/sally_smith/inbox",
  53   "outbox": "https://instance_url/api/v1/user/sally_smith/outbox",
  54   "liked": "https://instance_url/api/v1/user/sally_smith/liked",
  55   // TODO disliked?
  56   "following": "https://instance_url/api/v1/user/sally_smith/following",
  57   "name": "sally_smith",
  58   "preferredUsername": "Sally",
  59   "icon"?: {
  60     "type": "Image",
  61     "name": "User icon",
  62     "url": "https://instance_url/api/v1/user/sally_smith/icon.png",
  63     "width": 32,
  64     "height": 32
  65   },
  66   "published": "2014-12-31T23:00:00-08:00",
  67   "summary"?: "This is sally's profile."
  68 }
  69 ```
  70
  71 ### [Community / Group](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-group)
  72 ```
  73 {
  74   "@context": "https://www.w3.org/ns/activitystreams",
  75   "type": "Group",
  76   "id": "https://instance_url/api/v1/community/today_i_learned",
  77   "name": "today_i_learned"
  78   "attributedTo": [ // The moderators
  79     "http://joe.example.org",
  80   ],
  81   "followers": "https://instance_url/api/v1/community/today_i_learned/followers",
  82   "published": "2014-12-31T23:00:00-08:00",
  83   "summary"?: "The group's tagline",
  84   "attachment: [{}] // TBD, these would be where strong types for custom styles, and images would work.
  85 }
  86 ```
  87
  88 ## Objects
  89
  90 ### [Post / Page](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-page)
  91 ```
  92 {
  93   "@context": "https://www.w3.org/ns/activitystreams",
  94   "type": "Page",
  95   "id": "https://instance_url/api/v1/post/1",
  96   "name": "The title of a post, maybe a link to imgur",
  97   "url": "https://news.blah.com"
  98   "attributedTo": "http://joe.example.org", // The poster
  99   "published": "2014-12-31T23:00:00-08:00",
 100 }
 101 ```
 102
 103 ### [Post Listings / Ordered CollectionPage](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-orderedcollectionpage)
 104 ```
 105 {
 106   "@context": "https://www.w3.org/ns/activitystreams",
 107   "type": "OrderedCollectionPage",
 108   "id": "https://instance_url/api/v1/posts?type={all, best, front}&sort={}&page=1,
 109   "partOf": "http://example.org/foo",
 110   "orderedItems": [Posts]
 111 }
 112 ```
 113
 114 ### [Comment / Note](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-note)
 115 ```
 116 {
 117   "@context": "https://www.w3.org/ns/activitystreams",
 118   "type": "Note",
 119   "id": "https://instance_url/api/v1/comment/1",
 120   "mediaType": "text/markdown",
 121   "content": "Looks like it is going to rain today. Bring an umbrella *if necessary*!"
 122   "attributedTo": john_id,
 123   "inReplyTo": "comment or post id",
 124   "published": "2014-12-31T23:00:00-08:00",
 125   "updated"?: "2014-12-12T12:12:12Z"
 126   "replies" // TODO, not sure if these objects should embed all replies in them or not.
 127   "to": [sally_id, group_id]
 128 }
 129 ```
 130 ### [Comment Listings / Ordered CollectionPage](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-orderedcollectionpage)
 131 ```
 132 {
 133   "@context": "https://www.w3.org/ns/activitystreams",
 134   "type": "OrderedCollectionPage",
 135   "id": "https://instance_url/api/v1/comments?type={all,user,community,post,parent_comment}&id=1&page=1,
 136   "partOf": "http://example.org/foo",
 137   "orderedItems": [Comments]
 138 }
 139 ```
 140 ### [Deleted thing / Tombstone](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-tombstone)
 141 ```
 142 {
 143   "type": "Tombstone",
 144   "formerType": "Note / Post",
 145   "id": note / post_id,
 146   "deleted": "2016-03-17T00:00:00Z"
 147 }
 148 ```
 149 ## Actions
 150 - These are all posts to a user's outbox.
 151 - The server then creates a post to the necessary inbox of the recipient, or the followers.
 152 - Whenever a user accesses the site, they do a get from their inbox.
 153
 154 ### Comments
 155 #### [Create](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-create)
 156 ```
 157 {
 158   "@context": "https://www.w3.org/ns/activitystreams",
 159   "type": "Create",
 160   "actor": id,
 161   "object": comment_id, or post_id
 162 }
 163 ```
 164 #### [Delete](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-delete)
 165 ```
 166 {
 167   "@context": "https://www.w3.org/ns/activitystreams",
 168   "type": "Delete",
 169   "actor": id,
 170   "object": comment_id, or post_id
 171 }
 172 ```
 173 #### [Update](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-update)
 174 ```
 175 {
 176   "@context": "https://www.w3.org/ns/activitystreams",
 177   "type": "Create",
 178   "actor": id,
 179   "object": comment_id, or post_id
 180   "content": "New comment",
 181   "updated": "New Date"
 182 }
 183 ```
 184 #### [Read](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-read)
 185 ```
 186 {
 187   "@context": "https://www.w3.org/ns/activitystreams",
 188   "type": "Read",
 189   "actor": user_id
 190   "object": comment_id
 191 }
 192 ```
 193
 194 #### [Like](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-like)
 195 - TODO: Should likes be notifications? IE, have a to?
 196 ```
 197 {
 198   "@context": "https://www.w3.org/ns/activitystreams",
 199   "type": "Like",
 200   "actor": user_id
 201   "object": comment_id
 202   // TODO different types of reactions, or no?
 203 }
 204 ```
 205 #### [Dislike](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-dislike)
 206 ```
 207 {
 208   "@context": "https://www.w3.org/ns/activitystreams",
 209   "type": "Dislike",
 210   "actor": user_id
 211   "object": comment_id
 212   // TODO different types of reactions, or no?
 213 }
 214 ```
 215
 216 ### Posts
 217 #### [Create](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-create)
 218 ```
 219 {
 220   "@context": "https://www.w3.org/ns/activitystreams",
 221   "type": "Create",
 222   "actor": id,
 223   "to": community_id/followers
 224   "object": post_id
 225 }
 226 ```
 227 #### [Delete](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-delete)
 228 ```
 229 {
 230   "@context": "https://www.w3.org/ns/activitystreams",
 231   "type": "Delete",
 232   "actor": id,
 233   "object": comment_id, or post_id
 234 }
 235 ```
 236
 237 #### [Update](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-update)
 238 ```
 239 {
 240   "@context": "https://www.w3.org/ns/activitystreams",
 241   "type": "Create",
 242   "actor": id,
 243   "object": comment_id, or post_id
 244   TODO fields.
 245 }
 246 ```
 247 #### [Read](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-read)
 248 ```
 249 {
 250   "@context": "https://www.w3.org/ns/activitystreams",
 251   "type": "Read",
 252   "actor": user_id
 253   "object": post_id
 254 }
 255 ```
 256
 257 ### Communities
 258 #### [Create](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-create)
 259 ```
 260 {
 261   "@context": "https://www.w3.org/ns/activitystreams",
 262   "type": "Create",
 263   "actor": id,
 264   "object": community_id
 265 }
 266 ```
 267 #### [Delete](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-delete)
 268 ```
 269 {
 270   "@context": "https://www.w3.org/ns/activitystreams",
 271   "type": "Delete",
 272   "actor": id,
 273   "object": community_id
 274 }
 275 ```
 276
 277 #### [Update](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-update)
 278 ```
 279 {
 280   "@context": "https://www.w3.org/ns/activitystreams",
 281   "type": "Create",
 282   "actor": id,
 283   "object": community_id
 284   TODO fields.
 285 }
 286 ```
 287
 288 #### [Follow / Subscribe](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-follow)
 289 ```
 290 {
 291   "@context": "https://www.w3.org/ns/activitystreams",
 292   "type": "Follow",
 293   "actor": id
 294   "object": community_id
 295 }
 296 ```
 297
 298 #### [Ignore/ Unsubscribe](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-ignore)
 299 ```
 300 {
 301   "@context": "https://www.w3.org/ns/activitystreams",
 302   "type": "Follow",
 303   "actor": id
 304   "object": community_id
 305 }
 306 ```
 307 #### [Join / Become a Mod](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-join)
 308 ```
 309 {
 310   "@context": "https://www.w3.org/ns/activitystreams",
 311   "type": "Join",
 312   "actor": user_id,
 313   "object": community_id
 314 }
 315 ```
 316
 317 #### [Leave](https://www.w3.org/TR/activitystreams-vocabulary#dfn-leave)
 318 ```
 319 {
 320   "@context": "https://www.w3.org/ns/activitystreams",
 321   "type": "Leave",
 322   "actor": user_id,
 323   "object": community_id
 324 }
 325 ```
 326
 327 ### Moderator
 328 #### [Ban user from community / Block](https://www.w3.org/TR/activitystreams-vocabulary#dfn-block)
 329 ```
 330 {
 331   "@context": "https://www.w3.org/ns/activitystreams",
 332   "type": "Remove",
 333   "actor": mod_id,
 334   "object": user_id,
 335   "origin": group_id
 336 }
 337 ```
 338
 339 #### [Delete Comment](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-delete)
 340 ```
 341 {
 342   "@context": "https://www.w3.org/ns/activitystreams",
 343   "type": "Delete",
 344   "actor": id,
 345   "object": community_id
 346 }
 347 ```
 348
 349 #### [Invite a moderator](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-invite)
 350 ```
 351 {
 352   "@context": "https://www.w3.org/ns/activitystreams",
 353   "type": "Invite",
 354   "id": "https://instance_url/api/v1/invite/1",
 355   "actor": sally_id,
 356   "object": group_id,
 357   "target": john_id
 358 }
 359 ```
 360 #### [Accept Invitation](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-accept)
 361 ```
 362 {
 363   "@context": "https://www.w3.org/ns/activitystreams",
 364   "type": "Accept",
 365   "actor": john_id,
 366   "object": invite_id
 367 }
 368 ```
 369 #### [Reject Invitation](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-reject)
 370 ```
 371 {
 372   "@context": "https://www.w3.org/ns/activitystreams",
 373   "type": "Reject",
 374   "actor": john_id,
 375   "object": invite_id
 376 }
 377 ```
 378