X-Git-Url: http://these/git/?a=blobdiff_plain;f=docs%2Fsrc%2Fcontributing_websocket_http_api.md;h=ca2cceba6c5ee31f51c5b1c729665dffd4d5c9c3;hb=5c6258390c46159c16f49295314c6519215fc6ae;hp=6d1cf6909c77a715108ad057323fbc4214a2f3e2;hpb=b69524b498983da636b3a31f5acb74fbb1f13ab4;p=lemmy.git diff --git a/docs/src/contributing_websocket_http_api.md b/docs/src/contributing_websocket_http_api.md index 6d1cf690..ca2cceba 100644 --- a/docs/src/contributing_websocket_http_api.md +++ b/docs/src/contributing_websocket_http_api.md @@ -1,6 +1,6 @@ # Lemmy API -*Note: this may lag behind the actual API endpoints [here](../server/src/api). The API should be considered unstable and may change any time.* +*Note: this may lag behind the actual API endpoints [here](../src/api). The API should be considered unstable and may change any time.* @@ -28,214 +28,234 @@ - [Request](#request-1) - [Response](#response-1) - [HTTP](#http-2) - + [Get User Details](#get-user-details) + + [Get Captcha](#get-captcha) - [Request](#request-2) - [Response](#response-2) - [HTTP](#http-3) - + [Save User Settings](#save-user-settings) + + [Get User Details](#get-user-details) - [Request](#request-3) - [Response](#response-3) - [HTTP](#http-4) - + [Get Replies / Inbox](#get-replies--inbox) + + [Save User Settings](#save-user-settings) - [Request](#request-4) - [Response](#response-4) - [HTTP](#http-5) - + [Get User Mentions](#get-user-mentions) + + [Get Replies / Inbox](#get-replies--inbox) - [Request](#request-5) - [Response](#response-5) - [HTTP](#http-6) - + [Mark User Mention as read](#mark-user-mention-as-read) + + [Get User Mentions](#get-user-mentions) - [Request](#request-6) - [Response](#response-6) - [HTTP](#http-7) - + [Get Private Messages](#get-private-messages) + + [Mark User Mention as read](#mark-user-mention-as-read) - [Request](#request-7) - [Response](#response-7) - [HTTP](#http-8) - + [Create Private Message](#create-private-message) + + [Get Private Messages](#get-private-messages) - [Request](#request-8) - [Response](#response-8) - [HTTP](#http-9) - + [Edit Private Message](#edit-private-message) + + [Create Private Message](#create-private-message) - [Request](#request-9) - [Response](#response-9) - [HTTP](#http-10) - + [Delete Private Message](#delete-private-message) + + [Edit Private Message](#edit-private-message) - [Request](#request-10) - [Response](#response-10) - [HTTP](#http-11) - + [Mark Private Message as Read](#mark-private-message-as-read) + + [Delete Private Message](#delete-private-message) - [Request](#request-11) - [Response](#response-11) - [HTTP](#http-12) - + [Mark All As Read](#mark-all-as-read) + + [Mark Private Message as Read](#mark-private-message-as-read) - [Request](#request-12) - [Response](#response-12) - [HTTP](#http-13) - + [Delete Account](#delete-account) + + [Mark All As Read](#mark-all-as-read) - [Request](#request-13) - [Response](#response-13) - [HTTP](#http-14) - + [Add admin](#add-admin) + + [Delete Account](#delete-account) - [Request](#request-14) - [Response](#response-14) - [HTTP](#http-15) - + [Ban user](#ban-user) + + [Add admin](#add-admin) - [Request](#request-15) - [Response](#response-15) - [HTTP](#http-16) - * [Site](#site) - + [List Categories](#list-categories) + + [Ban user](#ban-user) - [Request](#request-16) - [Response](#response-16) - [HTTP](#http-17) - + [Search](#search) + + [User Join](#user-join) - [Request](#request-17) - [Response](#response-17) - [HTTP](#http-18) - + [Get Modlog](#get-modlog) + * [Site](#site) + + [List Categories](#list-categories) - [Request](#request-18) - [Response](#response-18) - [HTTP](#http-19) - + [Create Site](#create-site) + + [Search](#search) - [Request](#request-19) - [Response](#response-19) - [HTTP](#http-20) - + [Edit Site](#edit-site) + + [Get Modlog](#get-modlog) - [Request](#request-20) - [Response](#response-20) - [HTTP](#http-21) - + [Get Site](#get-site) + + [Create Site](#create-site) - [Request](#request-21) - [Response](#response-21) - [HTTP](#http-22) - + [Transfer Site](#transfer-site) + + [Edit Site](#edit-site) - [Request](#request-22) - [Response](#response-22) - [HTTP](#http-23) - + [Get Site Config](#get-site-config) + + [Get Site](#get-site) - [Request](#request-23) - [Response](#response-23) - [HTTP](#http-24) - + [Save Site Config](#save-site-config) + + [Transfer Site](#transfer-site) - [Request](#request-24) - [Response](#response-24) - [HTTP](#http-25) - * [Community](#community) - + [Get Community](#get-community) + + [Get Site Config](#get-site-config) - [Request](#request-25) - [Response](#response-25) - [HTTP](#http-26) - + [Create Community](#create-community) + + [Save Site Config](#save-site-config) - [Request](#request-26) - [Response](#response-26) - [HTTP](#http-27) - + [List Communities](#list-communities) + * [Community](#community) + + [Get Community](#get-community) - [Request](#request-27) - [Response](#response-27) - [HTTP](#http-28) - + [Ban from Community](#ban-from-community) + + [Create Community](#create-community) - [Request](#request-28) - [Response](#response-28) - [HTTP](#http-29) - + [Add Mod to Community](#add-mod-to-community) + + [List Communities](#list-communities) - [Request](#request-29) - [Response](#response-29) - [HTTP](#http-30) - + [Edit Community](#edit-community) + + [Ban from Community](#ban-from-community) - [Request](#request-30) - [Response](#response-30) - [HTTP](#http-31) - + [Delete Community](#delete-community) + + [Add Mod to Community](#add-mod-to-community) - [Request](#request-31) - [Response](#response-31) - [HTTP](#http-32) - + [Remove Community](#remove-community) + + [Edit Community](#edit-community) - [Request](#request-32) - [Response](#response-32) - [HTTP](#http-33) - + [Follow Community](#follow-community) + + [Delete Community](#delete-community) - [Request](#request-33) - [Response](#response-33) - [HTTP](#http-34) - + [Get Followed Communities](#get-followed-communities) + + [Remove Community](#remove-community) - [Request](#request-34) - [Response](#response-34) - [HTTP](#http-35) - + [Transfer Community](#transfer-community) + + [Follow Community](#follow-community) - [Request](#request-35) - [Response](#response-35) - [HTTP](#http-36) - * [Post](#post) - + [Create Post](#create-post) + + [Get Followed Communities](#get-followed-communities) - [Request](#request-36) - [Response](#response-36) - [HTTP](#http-37) - + [Get Post](#get-post) + + [Transfer Community](#transfer-community) - [Request](#request-37) - [Response](#response-37) - [HTTP](#http-38) - + [Get Posts](#get-posts) + + [Community Join](#community-join) - [Request](#request-38) - [Response](#response-38) - [HTTP](#http-39) - + [Create Post Like](#create-post-like) + * [Post](#post) + + [Create Post](#create-post) - [Request](#request-39) - [Response](#response-39) - [HTTP](#http-40) - + [Edit Post](#edit-post) + + [Get Post](#get-post) - [Request](#request-40) - [Response](#response-40) - [HTTP](#http-41) - + [Delete Post](#delete-post) + + [Get Posts](#get-posts) - [Request](#request-41) - [Response](#response-41) - [HTTP](#http-42) - + [Remove Post](#remove-post) + + [Create Post Like](#create-post-like) - [Request](#request-42) - [Response](#response-42) - [HTTP](#http-43) - + [Lock Post](#lock-post) + + [Edit Post](#edit-post) - [Request](#request-43) - [Response](#response-43) - [HTTP](#http-44) - + [Sticky Post](#sticky-post) + + [Delete Post](#delete-post) - [Request](#request-44) - [Response](#response-44) - [HTTP](#http-45) - + [Save Post](#save-post) + + [Remove Post](#remove-post) - [Request](#request-45) - [Response](#response-45) - [HTTP](#http-46) - * [Comment](#comment) - + [Create Comment](#create-comment) + + [Lock Post](#lock-post) - [Request](#request-46) - [Response](#response-46) - [HTTP](#http-47) - + [Edit Comment](#edit-comment) + + [Sticky Post](#sticky-post) - [Request](#request-47) - [Response](#response-47) - [HTTP](#http-48) - + [Delete Comment](#delete-comment) + + [Save Post](#save-post) - [Request](#request-48) - [Response](#response-48) - [HTTP](#http-49) - + [Remove Comment](#remove-comment) + + [Post Join](#post-join) - [Request](#request-49) - [Response](#response-49) - [HTTP](#http-50) - + [Mark Comment as Read](#mark-comment-as-read) + * [Comment](#comment) + + [Create Comment](#create-comment) - [Request](#request-50) - [Response](#response-50) - [HTTP](#http-51) - + [Save Comment](#save-comment) + + [Edit Comment](#edit-comment) - [Request](#request-51) - [Response](#response-51) - [HTTP](#http-52) - + [Create Comment Like](#create-comment-like) + + [Delete Comment](#delete-comment) - [Request](#request-52) - [Response](#response-52) - [HTTP](#http-53) + + [Remove Comment](#remove-comment) + - [Request](#request-53) + - [Response](#response-53) + - [HTTP](#http-54) + + [Get Comments](#get-comments) + - [Request](#request-54) + - [Response](#response-54) + - [HTTP](#http-55) + + [Mark Comment as Read](#mark-comment-as-read) + - [Request](#request-55) + - [Response](#response-55) + - [HTTP](#http-56) + + [Save Comment](#save-comment) + - [Request](#request-56) + - [Response](#response-56) + - [HTTP](#http-57) + + [Create Comment Like](#create-comment-like) + - [Request](#request-57) + - [Response](#response-57) + - [HTTP](#http-58) * [RSS / Atom feeds](#rss--atom-feeds) + [All](#all) + [Community](#community-1) @@ -249,7 +269,7 @@ - Option<***SomeType***> designates an option which may be omitted in requests and not be present in responses. It will be of type ***SomeType***. - Vec<***SomeType***> 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). +- Other data types are listed [here](../src/db). ## Basic usage @@ -261,6 +281,12 @@ Connect to ws://***host***/api/v1/ws to get started. If the ***`host`*** supports secure connections, you can use wss://***host***/api/v1/ws. +To receive websocket messages, you must join a room / context. The three available are: + +- [UserJoin](#user-join). Receives replies, private messages, etc. +- [PostJoin](#post-join). Receives new comments on a post. +- [CommunityJoin](#community-join). Receives front page / community posts. + #### Testing with Websocat [Websocat link](https://github.com/vi/websocat) @@ -839,6 +865,29 @@ Marks all user replies and mentions as read. `POST /user/ban` +#### User Join +##### Request +```rust +{ + op: "UserJoin", + data: { + auth: String + } +} +``` +##### Response +```rust +{ + op: "UserJoin", + data: { + joined: bool, + } +} +``` +##### HTTP + +`POST /user/join` + ### Site #### List Categories ##### Request @@ -1387,6 +1436,32 @@ Only admins can remove a community. `POST /community/transfer` +#### Community Join + +The main / frontpage community is `community_id: 0`. + +##### Request +```rust +{ + op: "CommunityJoin", + data: { + community_id: i32 + } +} +``` +##### Response +```rust +{ + op: "CommunityJoin", + data: { + joined: bool, + } +} +``` +##### HTTP + +`POST /community/join` + ### Post #### Create Post ##### Request @@ -1671,6 +1746,29 @@ Only admins and mods can sticky a post. `POST /post/save` +#### Post Join +##### Request +```rust +{ + op: "PostJoin", + data: { + post_id: i32 + } +} +``` +##### Response +```rust +{ + op: "PostJoin", + data: { + joined: bool, + } +} +``` +##### HTTP + +`POST /post/join` + ### Comment #### Create Comment ##### Request @@ -1787,6 +1885,38 @@ Only a mod or admin can remove the comment. `POST /comment/remove` +#### Get Comments + +Comment listing types are `All, Subscribed, Community` + +##### Request +```rust +{ + op: "GetComments", + data: { + type_: String, + sort: String, + page: Option, + limit: Option, + community_id: Option, + community_name: Option, + auth: Option + } +} +``` +##### Response +```rust +{ + op: "GetComments", + data: { + comments: Vec, + } +} +``` +##### HTTP + +`GET /comment/list` + #### Mark Comment as Read Only the recipient can do this.