From 089926496f6fbff6a902fd6b9857e0b259edf3e1 Mon Sep 17 00:00:00 2001 From: Dessalines Date: Mon, 25 Feb 2019 12:46:07 -0800 Subject: [PATCH] Initial outline of activitypub API --- API.md | 314 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 13 ++- 2 files changed, 322 insertions(+), 5 deletions(-) create mode 100644 API.md diff --git a/API.md b/API.md new file mode 100644 index 000000000..5c0658d7f --- /dev/null +++ b/API.md @@ -0,0 +1,314 @@ +# API + +- 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. + + + +- [Actors](#actors) + * [User / [Person](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-person)](#user--personhttpswwww3orgtractivitystreams-vocabulary%23dfn-person) + * [Community / [Group](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-group)](#community--grouphttpswwww3orgtractivitystreams-vocabulary%23dfn-group) +- [Objects](#objects) + * [Post / [Page](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-page)](#post--pagehttpswwww3orgtractivitystreams-vocabulary%23dfn-page) + * [Post Listings / [Ordered CollectionPage](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-orderedcollectionpage)](#post-listings--ordered-collectionpagehttpswwww3orgtractivitystreams-vocabulary%23dfn-orderedcollectionpage) + * [Comment / [Note](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-note)](#comment--notehttpswwww3orgtractivitystreams-vocabulary%23dfn-note) + * [Comment Listings / [Ordered CollectionPage](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-orderedcollectionpage)](#comment-listings--ordered-collectionpagehttpswwww3orgtractivitystreams-vocabulary%23dfn-orderedcollectionpage) + * [Deleted thing / [Tombstone](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-tombstone)](#deleted-thing--tombstonehttpswwww3orgtractivitystreams-vocabulary%23dfn-tombstone) +- [Actions](#actions) + * [Comments](#comments) + + [Create](#create) + + [Delete](#delete) + + [Update](#update) + + [Read](#read) + + [Like](#like) + + [Dislike](#dislike) + * [Posts](#posts) + + [Create](#create-1) + + [Delete](#delete-1) + + [Update](#update-1) + + [Read](#read-1) + * [Communities](#communities) + + [Create](#create-2) + + [Delete](#delete-2) + + [Update](#update-2) + + [Join](#join) + + [Leave](#leave) + + + +; +## Actors + +### User / [Person](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-person) +``` +{ + "@context": "https://www.w3.org/ns/activitystreams", + "type": "Person", + "id": "https://rust-reddit-fediverse/api/v1/user/sally_smith", + "name": "Sally Smith", // Their chosen alias + "icon"?: { + "type": "Image", + "name": "User icon", + "url": "https://rust-reddit-fediverse/api/v1/user/sally_smith/icon.png", + "width": 32, + "height": 32 + }, + "startTime": "2014-12-31T23:00:00-08:00", + "summary"?: "This is sally's profile." +} +``` + +### Community / [Group](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-group) + +``` +{ + "@context": "https://www.w3.org/ns/activitystreams", + "type": "Group", + "id": "https://rust-reddit-fediverse/api/v1/community/today_i_learned", + "name": "today_i_learned" + "attributedTo": [ // The moderators + "http://joe.example.org", + ], + "startTime": "2014-12-31T23:00:00-08:00", + "summary"?: "The group's tagline", + "attachment: [{}] // TBD, these would be where strong types for custom styles, and images would work. +} +``` + +## Objects + +### Post / [Page](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-page) +``` +{ + "@context": "https://www.w3.org/ns/activitystreams", + "type": "Page", + "id": "https://rust-reddit-fediverse/api/v1/post/1", + "name": "The title of a post, maybe a link to imgur", + "url": "https://news.blah.com" + "attributedTo": "http://joe.example.org", // The poster + "startTime": "2014-12-31T23:00:00-08:00", + +} +``` + +### Post Listings / [Ordered CollectionPage](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-orderedcollectionpage) + +``` +{ + "@context": "https://www.w3.org/ns/activitystreams", + "summary": "Page 1 of Sally's front page", + "type": "OrderedCollectionPage", + "id": "https://rust-reddit-fediverse/api/v1/posts?type={all, best, front}&sort={}&page=1, + "partOf": "http://example.org/foo", + "orderedItems": [Posts] +} +``` + +### Comment / [Note](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-note) +``` +{ + "@context": "https://www.w3.org/ns/activitystreams", + "type": "Note", + "id": "https://rust-reddit-fediverse/api/v1/comment/1", + "name": "A note", + "content": "Looks like it is going to rain today. Bring an umbrella!" + "attributedTo": "http://sally.example.org", + "inReplyTo": "comment or post id", + "startTime": "2014-12-31T23:00:00-08:00", + "updated"?: "2014-12-12T12:12:12Z" + "replies" // TODO, not sure if these objects should embed all replies in them or not. +} +``` +### Comment Listings / [Ordered CollectionPage](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-orderedcollectionpage) + +``` +{ + "@context": "https://www.w3.org/ns/activitystreams", + "summary": "Page 1 of comments for", + "type": "OrderedCollectionPage", + "id": "https://rust-reddit-fediverse/api/v1/comments?type={all,user,community,post,parent_comment}&id=1&page=1, + "partOf": "http://example.org/foo", + "orderedItems": [Comments] +} +``` +### Deleted thing / [Tombstone](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-tombstone) +``` +{ + "type": "Tombstone", + "formerType": "Note / Post", + "id": note / post_id, + "deleted": "2016-03-17T00:00:00Z" +} +``` +## Actions + +### Comments + +#### [Create](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-create) +``` +{ + "@context": "https://www.w3.org/ns/activitystreams", + "summary": "Sally created a note", + "type": "Create", + "actor": id, + "object": comment_id, or post_id +} +``` + +#### [Delete](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-delete) +``` +{ + "@context": "https://www.w3.org/ns/activitystreams", + "summary": "Sally deleted a note", + "type": "Delete", + "actor": id, + "object": comment_id, or post_id +} +``` +#### [Update](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-update) +``` +{ + "@context": "https://www.w3.org/ns/activitystreams", + "summary": "Sally created a note", + "type": "Create", + "actor": id, + "object": comment_id, or post_id + "content": "New comment", + "updated": "New Date" +} +``` +#### [Read](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-read) +``` +{ + "@context": "https://www.w3.org/ns/activitystreams", + "summary": "Sally read a comment", + "type": "Read", + "actor": user_id + "object": comment_id +} +``` + +#### [Like](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-like) +``` +{ + "@context": "https://www.w3.org/ns/activitystreams", + "summary": "Sally liked a comment", + "type": "Like", + "actor": user_id + "object": comment_id + // TODO different types of reactions, or no? +} +``` +#### [Dislike](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-dislike) +``` +{ + "@context": "https://www.w3.org/ns/activitystreams", + "summary": "Sally disliked a comment", + "type": "Dislike", + "actor": user_id + "object": comment_id + // TODO different types of reactions, or no? +} +``` + +### Posts + +#### [Create](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-create) +``` +{ + "@context": "https://www.w3.org/ns/activitystreams", + "summary": "Sally created a post", + "type": "Create", + "actor": id, + "object": post_id +} +``` +#### [Delete](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-delete) +``` +{ + "@context": "https://www.w3.org/ns/activitystreams", + "summary": "Sally deleted a post", + "type": "Delete", + "actor": id, + "object": comment_id, or post_id +} +``` + +#### [Update](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-update) +``` +{ + "@context": "https://www.w3.org/ns/activitystreams", + "summary": "Sally created a post", + "type": "Create", + "actor": id, + "object": comment_id, or post_id + TODO fields. +} +``` +#### [Read](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-read) +``` +{ + "@context": "https://www.w3.org/ns/activitystreams", + "summary": "Sally read a post", + "type": "Read", + "actor": user_id + "object": post_id +} +``` + +### Communities +#### [Create](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-create) +``` +{ + "@context": "https://www.w3.org/ns/activitystreams", + "summary": "Sally created a community", + "type": "Create", + "actor": id, + "object": community_id +} +``` +#### [Delete](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-delete) +``` +{ + "@context": "https://www.w3.org/ns/activitystreams", + "summary": "Sally deleted a community", + "type": "Delete", + "actor": id, + "object": community_id +} +``` + +#### [Update](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-update) +``` +{ + "@context": "https://www.w3.org/ns/activitystreams", + "summary": "Sally created a community", + "type": "Create", + "actor": id, + "object": community_id + TODO fields. +} +``` + +#### [Join](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-join) +``` +{ + "@context": "https://www.w3.org/ns/activitystreams", + "summary": "Sally joined a community", + "type": "Join", + "actor": user_id, + "object": community_id +} +``` + +#### [Leave](https://www.w3.org/TR/activitystreams-vocabulary#dfn-leave) +``` +{ + "@context": "https://www.w3.org/ns/activitystreams", + "summary": "Sally left a community", + "type": "Leave", + "actor": user_id, + "object": community_id +} +``` + +TODO - Moderator actions diff --git a/README.md b/README.md index 020235967..84a421ebc 100644 --- a/README.md +++ b/README.md @@ -5,11 +5,7 @@ We have a twitter alternative (mastodon), a facebook alternative (friendica), so [Matrix Chatroom](https://riot.im/app/#/room/#rust-reddit-fediverse:matrix.org) ## TODOs - -- Use the [activitypub crate.](https://docs.rs/activitypub/0.1.4/activitypub/) -- https://docs.rs/activitypub/0.1.4/activitypub/ -- [Activitypub vocab.](https://www.w3.org/TR/activitystreams-vocabulary/) -- Create a markdown doc of actions, matching up to things in that vocab. +- Create a markdown doc for ActivityPub actions: [API.md](API.md) ## Goals @@ -26,3 +22,10 @@ We have a twitter alternative (mastodon), a facebook alternative (friendica), so - Frontend: inferno, typescript and bootstrap for now. - Should it allow bots? - Should the comments / votes be static, or feel like a chat, like [flowchat?](https://flow-chat.com). + +## Resources / Potential Libraries +- Use the [activitypub crate.](https://docs.rs/activitypub/0.1.4/activitypub/) +- https://docs.rs/activitypub/0.1.4/activitypub/ +- [Activitypub vocab.](https://www.w3.org/TR/activitystreams-vocabulary/) + +