diff options
Diffstat (limited to 'docs/src/contributing_websocket_api.md')
| -rw-r--r-- | docs/src/contributing_websocket_api.md | 1031 |
1 files changed, 1031 insertions, 0 deletions
diff --git a/docs/src/contributing_websocket_api.md b/docs/src/contributing_websocket_api.md new file mode 100644 index 00000000..16383d53 --- /dev/null +++ b/docs/src/contributing_websocket_api.md @@ -0,0 +1,1031 @@ +# Lemmy API +*Note: this may lag behind the actual API endpoints [here](../server/src/api).* + +<!-- toc --> + +- [Data types](#data-types) +- [Basic usage](#basic-usage) + * [WebSocket Endpoint](#websocket-endpoint) + * [Testing with Websocat](#testing-with-websocat) + * [Testing with the WebSocket JavaScript API](#testing-with-the-websocket-javascript-api) +- [Rate limits](#rate-limits) +- [Errors](#errors) +- [API documentation](#api-documentation) + * [Sort Types](#sort-types) + * [User / Authentication / Admin actions](#user--authentication--admin-actions) + + [Login](#login) + - [Request](#request) + - [Response](#response) + + [Register](#register) + - [Request](#request-1) + - [Response](#response-1) + + [Get User Details](#get-user-details) + - [Request](#request-2) + - [Response](#response-2) + + [Save User Settings](#save-user-settings) + - [Request](#request-3) + - [Response](#response-3) + + [Get Replies / Inbox](#get-replies--inbox) + - [Request](#request-4) + - [Response](#response-4) + + [Get User Mentions](#get-user-mentions) + - [Request](#request-5) + - [Response](#response-5) + + [Mark All As Read](#mark-all-as-read) + - [Request](#request-6) + - [Response](#response-6) + + [Delete Account](#delete-account) + - [Request](#request-7) + - [Response](#response-7) + + [Add admin](#add-admin) + - [Request](#request-8) + - [Response](#response-8) + + [Ban user](#ban-user) + - [Request](#request-9) + - [Response](#response-9) + * [Site](#site) + + [List Categories](#list-categories) + - [Request](#request-10) + - [Response](#response-10) + + [Search](#search) + - [Request](#request-11) + - [Response](#response-11) + + [Get Modlog](#get-modlog) + - [Request](#request-12) + - [Response](#response-12) + + [Create Site](#create-site) + - [Request](#request-13) + - [Response](#response-13) + + [Edit Site](#edit-site) + - [Request](#request-14) + - [Response](#response-14) + + [Get Site](#get-site) + - [Request](#request-15) + - [Response](#response-15) + + [Transfer Site](#transfer-site) + - [Request](#request-16) + - [Response](#response-16) + * [Community](#community) + + [Get Community](#get-community) + - [Request](#request-17) + - [Response](#response-17) + + [Create Community](#create-community) + - [Request](#request-18) + - [Response](#response-18) + + [List Communities](#list-communities) + - [Request](#request-19) + - [Response](#response-19) + + [Ban from Community](#ban-from-community) + - [Request](#request-20) + - [Response](#response-20) + + [Add Mod to Community](#add-mod-to-community) + - [Request](#request-21) + - [Response](#response-21) + + [Edit Community](#edit-community) + - [Request](#request-22) + - [Response](#response-22) + + [Follow Community](#follow-community) + - [Request](#request-23) + - [Response](#response-23) + + [Get Followed Communities](#get-followed-communities) + - [Request](#request-24) + - [Response](#response-24) + + [Transfer Community](#transfer-community) + - [Request](#request-25) + - [Response](#response-25) + * [Post](#post) + + [Create Post](#create-post) + - [Request](#request-26) + - [Response](#response-26) + + [Get Post](#get-post) + - [Request](#request-27) + - [Response](#response-27) + + [Get Posts](#get-posts) + - [Request](#request-28) + - [Response](#response-28) + + [Create Post Like](#create-post-like) + - [Request](#request-29) + - [Response](#response-29) + + [Edit Post](#edit-post) + - [Request](#request-30) + - [Response](#response-30) + + [Save Post](#save-post) + - [Request](#request-31) + - [Response](#response-31) + * [Comment](#comment) + + [Create Comment](#create-comment) + - [Request](#request-32) + - [Response](#response-32) + + [Edit Comment](#edit-comment) + - [Request](#request-33) + - [Response](#response-33) + + [Save Comment](#save-comment) + - [Request](#request-34) + - [Response](#response-34) + + [Create Comment Like](#create-comment-like) + - [Request](#request-35) + - [Response](#response-35) + * [RSS / Atom feeds](#rss--atom-feeds) + + [All](#all) + + [Community](#community-1) + + [User](#user) + +<!-- tocstop --> + +## Data types + +- `i16`, `i32` and `i64` are respectively [16-bit](https://en.wikipedia.org/wiki/16-bit), [32-bit](https://en.wikipedia.org/wiki/32-bit) and [64-bit](https://en.wikipedia.org/wiki/64-bit_computing) integers. +- <code>Option<***SomeType***></code> designates an option which may be omitted in requests and not be present in responses. It will be of type ***SomeType***. +- <code>Vec<***SomeType***></code> is a list which contains objects of type ***SomeType***. +- `chrono::NaiveDateTime` is a timestamp string in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Timestamps will be UTC. +- Other data types are listed [here](../server/src/db). + +## Basic usage + +Request and response strings are in [JSON format](https://www.json.org). + +### WebSocket Endpoint + +Connect to <code>ws://***host***/api/v1/ws</code> to get started. + +If the ***`host`*** supports secure connections, you can use <code>wss://***host***/api/v1/ws</code>. + +### Testing with Websocat + +[Websocat link](https://github.com/vi/websocat) + +`websocat ws://127.0.0.1:8536/api/v1/ws -nt` + +A simple test command: +`{"op": "ListCategories"}` + +### Testing with the WebSocket JavaScript API + +[WebSocket JavaScript API](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) +```javascript +var ws = new WebSocket("ws://" + host + "/api/v1/ws"); +ws.onopen = function () { + console.log("Connection succeed!"); + ws.send(JSON.stringify({ + op: "ListCategories" + })); +}; +``` + +## Rate limits + +- 1 per hour for signups and community creation. +- 1 per 10 minutes for post creation. +- 30 actions per minute for post voting and comment creation. +- Everything else is not rate-limited. + +## Errors +```rust +{ + op: String, + message: String, +} +``` + +## API documentation + +### Sort Types + +These go wherever there is a `sort` field. The available sort types are: + +- `Hot` - the hottest posts/communities, depending on votes, views, comments and publish date +- `New` - the newest posts/communities +- `TopDay` - the most upvoted posts/communities of the current day. +- `TopWeek` - the most upvoted posts/communities of the current week. +- `TopMonth` - the most upvoted posts/communities of the current month. +- `TopYear` - the most upvoted posts/communities of the current year. +- `TopAll` - the most upvoted posts/communities on the current instance. + +### User / Authentication / Admin actions + +#### Login + +The `jwt` string should be stored and used anywhere `auth` is called for. + +##### Request +```rust +{ + op: "Login", + data: { + username_or_email: String, + password: String + } +} +``` +##### Response +```rust +{ + op: String, + jwt: String +} +``` + + +#### Register +Only the first user will be able to be the admin. + +##### Request +```rust +{ + op: "Register", + data: { + username: String, + email: Option<String>, + password: String, + password_verify: String, + admin: bool + } +} +``` +##### Response +```rust +{ + op: String, + jwt: String +} +``` + +#### Get User Details +##### Request +```rust +{ + op: "GetUserDetails", + data: { + user_id: Option<i32>, + username: Option<String>, + sort: String, + page: Option<i64>, + limit: Option<i64>, + community_id: Option<i32>, + saved_only: bool, + auth: Option<String>, + } +} +``` +##### Response +```rust +{ + op: String, + user: UserView, + follows: Vec<CommunityFollowerView>, + moderates: Vec<CommunityModeratorView>, + comments: Vec<CommentView>, + posts: Vec<PostView>, +} +``` +#### Save User Settings +##### Request +```rust +{ + op: "SaveUserSettings", + data: { + show_nsfw: bool, + theme: String, // Default 'darkly' + default_sort_type: i16, // The Sort types from above, zero indexed as a number + default_listing_type: i16, // Post listing types are `All, Subscribed, Community` + auth: String + } +} +``` +##### Response +```rust +{ + op: String, + jwt: String +} +``` +#### Get Replies / Inbox +##### Request +```rust +{ + op: "GetReplies", + data: { + sort: String, + page: Option<i64>, + limit: Option<i64>, + unread_only: bool, + auth: String + } +} +``` +##### Response +```rust +{ + op: String, + replies: Vec<ReplyView>, +} +``` + +#### Get User Mentions +##### Request +```rust +{ + op: "GetUserMentions", + data: { + sort: String, + page: Option<i64>, + limit: Option<i64>, + unread_only: bool, + auth: String, + } +} +``` +##### Response +```rust +{ + op: String, + mentions: Vec<UserMentionView>, +} +``` + +#### Mark All As Read + +Marks all user replies and mentions as read. + +##### Request +```rust +{ + op: "MarkAllAsRead", + data: { + auth: String + } +} +``` +##### Response +```rust +{ + op: String, + replies: Vec<ReplyView>, +} +``` + +#### Delete Account + +*Permananently deletes your posts and comments* + +##### Request +```rust +{ + op: "DeleteAccount", + data: { + password: String, + auth: String + } +} +``` +##### Response +```rust +{ + op: String, + jwt: String, +} +``` + +#### Add admin +##### Request +```rust +{ + op: "AddAdmin", + data: { + user_id: i32, + added: bool, + auth: String + } +} +``` +##### Response +```rust +{ + op: String, + admins: Vec<UserView>, +} +``` + +#### Ban user +##### Request +```rust +{ + op: "BanUser", + data: { + user_id: i32, + ban: bool, + reason: Option<String>, + expires: Option<i64>, + auth: String + } +} +``` +##### Response +```rust +{ + op: String, + user: UserView, + banned: bool, +} +``` + +### Site +#### List Categories +##### Request +```rust +{ + op: "ListCategories" +} +``` +##### Response +```rust +{ + op: String, + categories: Vec<Category> +} +``` + +#### Search +Search types are `Both, Comments, Posts`. + +##### Request +```rust +{ + op: "Search", + data: { + q: String, + type_: String, + community_id: Option<i32>, + sort: String, + page: Option<i64>, + limit: Option<i64>, + } +} +``` +##### Response +```rust +{ + op: String, + comments: Vec<CommentView>, + posts: Vec<PostView>, +} +``` + +#### Get Modlog +##### Request +```rust +{ + op: "GetModlog", + data: { + mod_user_id: Option<i32>, + community_id: Option<i32>, + page: Option<i64>, + limit: Option<i64>, + } +} +``` +##### Response +```rust +{ + op: String, + removed_posts: Vec<ModRemovePostView>, + locked_posts: Vec<ModLockPostView>, + removed_comments: Vec<ModRemoveCommentView>, + removed_communities: Vec<ModRemoveCommunityView>, + banned_from_community: Vec<ModBanFromCommunityView>, + banned: Vec<ModBanView>, + added_to_community: Vec<ModAddCommunityView>, + added: Vec<ModAddView>, +} +``` + +#### Create Site +##### Request +```rust +{ + op: "CreateSite", + data: { + name: String, + description: Option<String>, + auth: String + } +} +``` +##### Response +```rust +{ + op: String, + site: SiteView, +} +``` + +#### Edit Site +##### Request +```rust +{ + op: "EditSite", + data: { + name: String, + description: Option<String>, + auth: String + } +} +``` +##### Response +```rust +{ + op: String, + site: SiteView, +} +``` + +#### Get Site +##### Request +```rust +{ + op: "GetSite" +} +``` +##### Response +```rust +{ + op: String, + site: Option<SiteView>, + admins: Vec<UserView>, + banned: Vec<UserView>, +} +``` + +#### Transfer Site +##### Request +```rust +{ + op: "TransferSite", + data: { + user_id: i32, + auth: String + } +} +``` +##### Response +```rust +{ + op: String, + site: Option<SiteView>, + admins: Vec<UserView>, + banned: Vec<UserView>, +} +``` + +### Community +#### Get Community +##### Request +```rust +{ + op: "GetCommunity", + data: { + id: Option<i32>, + name: Option<String>, + auth: Option<String> + } +} +``` +##### Response +```rust +{ + op: String, + community: CommunityView, + moderators: Vec<CommunityModeratorView>, + admins: Vec<UserView>, +} +``` + +#### Create Community +##### Request +```rust +{ + op: "CreateCommunity", + data: { + name: String, + title: String, + description: Option<String>, + category_id: i32 , + auth: String + } +} +``` +##### Response +```rust +{ + op: String, + community: CommunityView +} +``` + +#### List Communities +##### Request +```rust +{ + op: "ListCommunities", + data: { + sort: String, + page: Option<i64>, + limit: Option<i64>, + auth: Option<String> + } +} +``` +##### Response +```rust +{ + op: String, + communities: Vec<CommunityView> +} +``` + +#### Ban from Community +##### Request +```rust +{ + op: "BanFromCommunity", + data: { + community_id: i32, + user_id: i32, + ban: bool, + reason: Option<String>, + expires: Option<i64>, + auth: String + } +} +``` +##### Response +```rust +{ + op: String, + user: UserView, + banned: bool, +} +``` + +#### Add Mod to Community +##### Request +```rust +{ + op: "AddModToCommunity", + data: { + community_id: i32, + user_id: i32, + added: bool, + auth: String + } +} +``` +##### Response +```rust +{ + op: String, + moderators: Vec<CommunityModeratorView>, +} +``` + +#### Edit Community +Mods and admins can remove and lock a community, creators can delete it. + +##### Request +```rust +{ + op: "EditCommunity", + data: { + edit_id: i32, + name: String, + title: String, + description: Option<String>, + category_id: i32, + removed: Option<bool>, + deleted: Option<bool>, + reason: Option<String>, + expires: Option<i64>, + auth: String + } +} +``` +##### Response +```rust +{ + op: String, + community: CommunityView +} +``` + +#### Follow Community +##### Request +```rust +{ + op: "FollowCommunity", + data: { + community_id: i32, + follow: bool, + auth: String + } +} +``` +##### Response +```rust +{ + op: String, + community: CommunityView +} +``` + +#### Get Followed Communities +##### Request +```rust +{ + op: "GetFollowedCommunities", + data: { + auth: String + } +} +``` +##### Response +```rust +{ + op: String, + communities: Vec<CommunityFollowerView> +} +``` + +#### Transfer Community +##### Request +```rust +{ + op: "TransferCommunity", + data: { + community_id: i32, + user_id: i32, + auth: String + } +} +``` +##### Response +```rust +{ + op: String, + community: CommunityView, + moderators: Vec<CommunityModeratorView>, + admins: Vec<UserView>, +} +``` + +### Post +#### Create Post +##### Request +```rust +{ + op: "CreatePost", + data: { + name: String, + url: Option<String>, + body: Option<String>, + community_id: i32, + auth: String + } +} +``` +##### Response +```rust +{ + op: String, + post: PostView +} +``` + +#### Get Post +##### Request +```rust +{ + op: "GetPost", + data: { + id: i32, + auth: Option<String> + } +} +``` +##### Response +```rust +{ + op: String, + post: PostView, + comments: Vec<CommentView>, + community: CommunityView, + moderators: Vec<CommunityModeratorView>, + admins: Vec<UserView>, +} +``` + +#### Get Posts +Post listing types are `All, Subscribed, Community` + +##### Request +```rust +{ + op: "GetPosts", + data: { + type_: String, + sort: String, + page: Option<i64>, + limit: Option<i64>, + community_id: Option<i32>, + auth: Option<String> + } +} +``` +##### Response +```rust +{ + op: String, + posts: Vec<PostView>, +} +``` + +#### Create Post Like +`score` can be 0, -1, or 1 + +##### Request +```rust +{ + op: "CreatePostLike", + data: { + post_id: i32, + score: i16, + auth: String + } +} +``` +##### Response +```rust +{ + op: String, + post: PostView +} +``` + +#### Edit Post +Mods and admins can remove and lock a post, creators can delete it. + +##### Request +```rust +{ + op: "EditPost", + data: { + edit_id: i32, + creator_id: i32, + community_id: i32, + name: String, + url: Option<String>, + body: Option<String>, + removed: Option<bool>, + deleted: Option<bool>, + locked: Option<bool>, + reason: Option<String>, + auth: String + } +} +``` +##### Response +```rust +{ + op: String, + post: PostView +} +``` + +#### Save Post +##### Request +```rust +{ + op: "SavePost", + data: { + post_id: i32, + save: bool, + auth: String + } +} +``` +##### Response +```rust +{ + op: String, + post: PostView +} +``` + +### Comment +#### Create Comment +##### Request +```rust +{ + op: "CreateComment", + data: { + content: String, + parent_id: Option<i32>, + edit_id: Option<i32>, + post_id: i32, + auth: String + } +} +``` +##### Response +```rust +{ + op: String, + comment: CommentView +} +``` + +#### Edit Comment +Mods and admins can remove a comment, creators can delete it. + +##### Request +```rust +{ + op: "EditComment", + data: { + content: String, + parent_id: Option<i32>, + edit_id: i32, + creator_id: i32, + post_id: i32, + removed: Option<bool>, + deleted: Option<bool>, + reason: Option<String>, + read: Option<bool>, + auth: String + } +} +``` +##### Response +```rust +{ + op: String, + comment: CommentView +} +``` + +#### Save Comment +##### Request +```rust +{ + op: "SaveComment", + data: { + comment_id: i32, + save: bool, + auth: String + } +} +``` +##### Response +```rust +{ + op: String, + comment: CommentView +} +``` + +#### Create Comment Like +`score` can be 0, -1, or 1 + +##### Request +```rust +{ + op: "CreateCommentLike", + data: { + comment_id: i32, + post_id: i32, + score: i16, + auth: String + } +} +``` +##### Response +```rust +{ + op: String, + comment: CommentView +} +``` + +### RSS / Atom feeds + +#### All + +`/feeds/all.xml?sort=Hot` + +#### Community + +`/feeds/c/community-name.xml?sort=Hot` + +#### User + +`/feeds/u/user-name.xml?sort=Hot` + |