diff options
63 files changed, 2970 insertions, 1096 deletions
@@ -157,15 +157,15 @@ If you'd like to add translations, take a look a look at the [English translatio lang | done | missing --- | --- | --- -de | 93% | avatar,upload_avatar,show_avatars,docs,old_password,send_notifications_to_email,downvotes_disabled,enable_downvotes,open_registration,registration_closed,enable_nsfw,donate_to_lemmy,donate,email_already_exists -eo | 80% | number_of_communities,preview,upload_image,avatar,upload_avatar,show_avatars,formatting_help,view_source,sticky,unsticky,archive_link,stickied,delete_account,delete_account_confirm,banned,creator,number_online,docs,replies,mentions,old_password,forgot_password,reset_password_mail_sent,password_change,new_password,no_email_setup,send_notifications_to_email,language,browser_default,downvotes_disabled,enable_downvotes,open_registration,registration_closed,enable_nsfw,theme,donate_to_lemmy,donate,are_you_sure,yes,no,email_already_exists -es | 89% | avatar,upload_avatar,show_avatars,archive_link,docs,replies,mentions,old_password,forgot_password,reset_password_mail_sent,password_change,new_password,no_email_setup,send_notifications_to_email,language,browser_default,downvotes_disabled,enable_downvotes,open_registration,registration_closed,enable_nsfw,donate_to_lemmy,donate,email_already_exists -fr | 89% | avatar,upload_avatar,show_avatars,archive_link,docs,replies,mentions,old_password,forgot_password,reset_password_mail_sent,password_change,new_password,no_email_setup,send_notifications_to_email,language,browser_default,downvotes_disabled,enable_downvotes,open_registration,registration_closed,enable_nsfw,donate_to_lemmy,donate,email_already_exists -it | 89% | avatar,upload_avatar,show_avatars,archive_link,docs,old_password,forgot_password,reset_password_mail_sent,password_change,new_password,no_email_setup,send_notifications_to_email,language,browser_default,downvotes_disabled,enable_downvotes,open_registration,registration_closed,enable_nsfw,donate_to_lemmy,donate,email_already_exists -nl | 99% | donate_to_lemmy,donate,email_already_exists -ru | 77% | cross_posts,cross_post,number_of_communities,preview,upload_image,avatar,upload_avatar,show_avatars,formatting_help,view_source,sticky,unsticky,archive_link,stickied,delete_account,delete_account_confirm,banned,creator,number_online,docs,replies,mentions,old_password,forgot_password,reset_password_mail_sent,password_change,new_password,no_email_setup,send_notifications_to_email,language,browser_default,downvotes_disabled,enable_downvotes,open_registration,registration_closed,enable_nsfw,recent_comments,theme,donate_to_lemmy,donate,monero,by,to,transfer_community,transfer_site,are_you_sure,yes,no,email_already_exists -sv | 89% | avatar,upload_avatar,show_avatars,archive_link,docs,replies,mentions,old_password,forgot_password,reset_password_mail_sent,password_change,new_password,no_email_setup,send_notifications_to_email,language,browser_default,downvotes_disabled,enable_downvotes,open_registration,registration_closed,enable_nsfw,donate_to_lemmy,donate,email_already_exists -zh | 75% | cross_posts,cross_post,users,number_of_communities,preview,upload_image,avatar,upload_avatar,show_avatars,formatting_help,view_source,sticky,unsticky,archive_link,settings,stickied,delete_account,delete_account_confirm,banned,creator,number_online,docs,replies,mentions,old_password,forgot_password,reset_password_mail_sent,password_change,new_password,no_email_setup,send_notifications_to_email,language,browser_default,downvotes_disabled,enable_downvotes,open_registration,registration_closed,enable_nsfw,recent_comments,nsfw,show_nsfw,theme,donate_to_lemmy,donate,monero,by,to,transfer_community,transfer_site,are_you_sure,yes,no,email_already_exists +de | 88% | create_private_message,send_secure_message,send_message,message,avatar,upload_avatar,show_avatars,docs,message_sent,messages,old_password,matrix_user_id,private_message_disclaimer,send_notifications_to_email,downvotes_disabled,enable_downvotes,open_registration,registration_closed,enable_nsfw,donate_to_lemmy,donate,from,logged_in,email_already_exists,couldnt_create_private_message,no_private_message_edit_allowed,couldnt_update_private_message +eo | 76% | number_of_communities,create_private_message,send_secure_message,send_message,message,preview,upload_image,avatar,upload_avatar,show_avatars,formatting_help,view_source,sticky,unsticky,archive_link,stickied,delete_account,delete_account_confirm,banned,creator,number_online,docs,replies,mentions,message_sent,messages,old_password,forgot_password,reset_password_mail_sent,password_change,new_password,no_email_setup,matrix_user_id,private_message_disclaimer,send_notifications_to_email,language,browser_default,downvotes_disabled,enable_downvotes,open_registration,registration_closed,enable_nsfw,theme,donate_to_lemmy,donate,from,are_you_sure,yes,no,logged_in,email_already_exists,couldnt_create_private_message,no_private_message_edit_allowed,couldnt_update_private_message +es | 83% | create_private_message,send_secure_message,send_message,message,avatar,upload_avatar,show_avatars,archive_link,docs,replies,mentions,message_sent,messages,old_password,forgot_password,reset_password_mail_sent,password_change,new_password,no_email_setup,matrix_user_id,private_message_disclaimer,send_notifications_to_email,language,browser_default,downvotes_disabled,enable_downvotes,open_registration,registration_closed,enable_nsfw,donate_to_lemmy,donate,from,logged_in,email_already_exists,couldnt_create_private_message,no_private_message_edit_allowed,couldnt_update_private_message +fr | 83% | create_private_message,send_secure_message,send_message,message,avatar,upload_avatar,show_avatars,archive_link,docs,replies,mentions,message_sent,messages,old_password,forgot_password,reset_password_mail_sent,password_change,new_password,no_email_setup,matrix_user_id,private_message_disclaimer,send_notifications_to_email,language,browser_default,downvotes_disabled,enable_downvotes,open_registration,registration_closed,enable_nsfw,donate_to_lemmy,donate,from,logged_in,email_already_exists,couldnt_create_private_message,no_private_message_edit_allowed,couldnt_update_private_message +it | 84% | create_private_message,send_secure_message,send_message,message,avatar,upload_avatar,show_avatars,archive_link,docs,message_sent,messages,old_password,forgot_password,reset_password_mail_sent,password_change,new_password,no_email_setup,matrix_user_id,private_message_disclaimer,send_notifications_to_email,language,browser_default,downvotes_disabled,enable_downvotes,open_registration,registration_closed,enable_nsfw,donate_to_lemmy,donate,from,logged_in,email_already_exists,couldnt_create_private_message,no_private_message_edit_allowed,couldnt_update_private_message +nl | 93% | create_private_message,send_secure_message,send_message,message,message_sent,messages,matrix_user_id,private_message_disclaimer,donate_to_lemmy,donate,from,logged_in,email_already_exists,couldnt_create_private_message,no_private_message_edit_allowed,couldnt_update_private_message +ru | 72% | cross_posts,cross_post,number_of_communities,create_private_message,send_secure_message,send_message,message,preview,upload_image,avatar,upload_avatar,show_avatars,formatting_help,view_source,sticky,unsticky,archive_link,stickied,delete_account,delete_account_confirm,banned,creator,number_online,docs,replies,mentions,message_sent,messages,old_password,forgot_password,reset_password_mail_sent,password_change,new_password,no_email_setup,matrix_user_id,private_message_disclaimer,send_notifications_to_email,language,browser_default,downvotes_disabled,enable_downvotes,open_registration,registration_closed,enable_nsfw,recent_comments,theme,donate_to_lemmy,donate,monero,by,to,from,transfer_community,transfer_site,are_you_sure,yes,no,logged_in,email_already_exists,couldnt_create_private_message,no_private_message_edit_allowed,couldnt_update_private_message +sv | 83% | create_private_message,send_secure_message,send_message,message,avatar,upload_avatar,show_avatars,archive_link,docs,replies,mentions,message_sent,messages,old_password,forgot_password,reset_password_mail_sent,password_change,new_password,no_email_setup,matrix_user_id,private_message_disclaimer,send_notifications_to_email,language,browser_default,downvotes_disabled,enable_downvotes,open_registration,registration_closed,enable_nsfw,donate_to_lemmy,donate,from,logged_in,email_already_exists,couldnt_create_private_message,no_private_message_edit_allowed,couldnt_update_private_message +zh | 70% | cross_posts,cross_post,users,number_of_communities,create_private_message,send_secure_message,send_message,message,preview,upload_image,avatar,upload_avatar,show_avatars,formatting_help,view_source,sticky,unsticky,archive_link,settings,stickied,delete_account,delete_account_confirm,banned,creator,number_online,docs,replies,mentions,message_sent,messages,old_password,forgot_password,reset_password_mail_sent,password_change,new_password,no_email_setup,matrix_user_id,private_message_disclaimer,send_notifications_to_email,language,browser_default,downvotes_disabled,enable_downvotes,open_registration,registration_closed,enable_nsfw,recent_comments,nsfw,show_nsfw,theme,donate_to_lemmy,donate,monero,by,to,from,transfer_community,transfer_site,are_you_sure,yes,no,logged_in,email_already_exists,couldnt_create_private_message,no_private_message_edit_allowed,couldnt_update_private_message <!-- translationsstop --> diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index d8916974..c2df6223 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -12,5 +12,5 @@ - [Contributing](contributing.md) - [Docker Development](contributing_docker_development.md) - [Local Development](contributing_local_development.md) - - [Websocket API](contributing_websocket_api.md) + - [Websocket/HTTP API](contributing_websocket_http_api.md) - [ActivityPub API Outline](contributing_apub_api_outline.md) diff --git a/docs/src/contributing_websocket_api.md b/docs/src/contributing_websocket_http_api.md index 16383d53..9e87d4fa 100644 --- a/docs/src/contributing_websocket_api.md +++ b/docs/src/contributing_websocket_http_api.md @@ -5,126 +5,171 @@ - [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) + * [WebSocket](#websocket) + + [Testing with Websocat](#testing-with-websocat) + + [Testing with the WebSocket JavaScript API](#testing-with-the-websocket-javascript-api) + * [HTTP](#http) + + [Testing with Curl](#testing-with-curl) + - [Get Example](#get-example) + - [Post Example](#post-example) - [Rate limits](#rate-limits) - [Errors](#errors) - [API documentation](#api-documentation) * [Sort Types](#sort-types) + * [Websocket vs HTTP](#websocket-vs-http) * [User / Authentication / Admin actions](#user--authentication--admin-actions) + [Login](#login) - [Request](#request) - [Response](#response) + - [HTTP](#http-1) + [Register](#register) - [Request](#request-1) - [Response](#response-1) + - [HTTP](#http-2) + [Get User Details](#get-user-details) - [Request](#request-2) - [Response](#response-2) + - [HTTP](#http-3) + [Save User Settings](#save-user-settings) - [Request](#request-3) - [Response](#response-3) + - [HTTP](#http-4) + [Get Replies / Inbox](#get-replies--inbox) - [Request](#request-4) - [Response](#response-4) + - [HTTP](#http-5) + [Get User Mentions](#get-user-mentions) - [Request](#request-5) - [Response](#response-5) - + [Mark All As Read](#mark-all-as-read) + - [HTTP](#http-6) + + [Edit User Mention](#edit-user-mention) - [Request](#request-6) - [Response](#response-6) - + [Delete Account](#delete-account) + - [HTTP](#http-7) + + [Mark All As Read](#mark-all-as-read) - [Request](#request-7) - [Response](#response-7) - + [Add admin](#add-admin) + - [HTTP](#http-8) + + [Delete Account](#delete-account) - [Request](#request-8) - [Response](#response-8) - + [Ban user](#ban-user) + - [HTTP](#http-9) + + [Add admin](#add-admin) - [Request](#request-9) - [Response](#response-9) - * [Site](#site) - + [List Categories](#list-categories) + - [HTTP](#http-10) + + [Ban user](#ban-user) - [Request](#request-10) - [Response](#response-10) - + [Search](#search) + - [HTTP](#http-11) + * [Site](#site) + + [List Categories](#list-categories) - [Request](#request-11) - [Response](#response-11) - + [Get Modlog](#get-modlog) + - [HTTP](#http-12) + + [Search](#search) - [Request](#request-12) - [Response](#response-12) - + [Create Site](#create-site) + - [HTTP](#http-13) + + [Get Modlog](#get-modlog) - [Request](#request-13) - [Response](#response-13) - + [Edit Site](#edit-site) + - [HTTP](#http-14) + + [Create Site](#create-site) - [Request](#request-14) - [Response](#response-14) - + [Get Site](#get-site) + - [HTTP](#http-15) + + [Edit Site](#edit-site) - [Request](#request-15) - [Response](#response-15) - + [Transfer Site](#transfer-site) + - [HTTP](#http-16) + + [Get Site](#get-site) - [Request](#request-16) - [Response](#response-16) - * [Community](#community) - + [Get Community](#get-community) + - [HTTP](#http-17) + + [Transfer Site](#transfer-site) - [Request](#request-17) - [Response](#response-17) - + [Create Community](#create-community) + - [HTTP](#http-18) + * [Community](#community) + + [Get Community](#get-community) - [Request](#request-18) - [Response](#response-18) - + [List Communities](#list-communities) + - [HTTP](#http-19) + + [Create Community](#create-community) - [Request](#request-19) - [Response](#response-19) - + [Ban from Community](#ban-from-community) + - [HTTP](#http-20) + + [List Communities](#list-communities) - [Request](#request-20) - [Response](#response-20) - + [Add Mod to Community](#add-mod-to-community) + - [HTTP](#http-21) + + [Ban from Community](#ban-from-community) - [Request](#request-21) - [Response](#response-21) - + [Edit Community](#edit-community) + - [HTTP](#http-22) + + [Add Mod to Community](#add-mod-to-community) - [Request](#request-22) - [Response](#response-22) - + [Follow Community](#follow-community) + - [HTTP](#http-23) + + [Edit Community](#edit-community) - [Request](#request-23) - [Response](#response-23) - + [Get Followed Communities](#get-followed-communities) + - [HTTP](#http-24) + + [Follow Community](#follow-community) - [Request](#request-24) - [Response](#response-24) - + [Transfer Community](#transfer-community) + - [HTTP](#http-25) + + [Get Followed Communities](#get-followed-communities) - [Request](#request-25) - [Response](#response-25) - * [Post](#post) - + [Create Post](#create-post) + - [HTTP](#http-26) + + [Transfer Community](#transfer-community) - [Request](#request-26) - [Response](#response-26) - + [Get Post](#get-post) + - [HTTP](#http-27) + * [Post](#post) + + [Create Post](#create-post) - [Request](#request-27) - [Response](#response-27) - + [Get Posts](#get-posts) + - [HTTP](#http-28) + + [Get Post](#get-post) - [Request](#request-28) - [Response](#response-28) - + [Create Post Like](#create-post-like) + - [HTTP](#http-29) + + [Get Posts](#get-posts) - [Request](#request-29) - [Response](#response-29) - + [Edit Post](#edit-post) + - [HTTP](#http-30) + + [Create Post Like](#create-post-like) - [Request](#request-30) - [Response](#response-30) - + [Save Post](#save-post) + - [HTTP](#http-31) + + [Edit Post](#edit-post) - [Request](#request-31) - [Response](#response-31) - * [Comment](#comment) - + [Create Comment](#create-comment) + - [HTTP](#http-32) + + [Save Post](#save-post) - [Request](#request-32) - [Response](#response-32) - + [Edit Comment](#edit-comment) + - [HTTP](#http-33) + * [Comment](#comment) + + [Create Comment](#create-comment) - [Request](#request-33) - [Response](#response-33) - + [Save Comment](#save-comment) + - [HTTP](#http-34) + + [Edit Comment](#edit-comment) - [Request](#request-34) - [Response](#response-34) - + [Create Comment Like](#create-comment-like) + - [HTTP](#http-35) + + [Save Comment](#save-comment) - [Request](#request-35) - [Response](#response-35) + - [HTTP](#http-36) + + [Create Comment Like](#create-comment-like) + - [Request](#request-36) + - [Response](#response-36) + - [HTTP](#http-37) * [RSS / Atom feeds](#rss--atom-feeds) + [All](#all) + [Community](#community-1) @@ -144,13 +189,13 @@ Request and response strings are in [JSON format](https://www.json.org). -### WebSocket Endpoint +### WebSocket 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 +#### Testing with Websocat [Websocat link](https://github.com/vi/websocat) @@ -159,7 +204,7 @@ If the ***`host`*** supports secure connections, you can use <code>wss://***host A simple test command: `{"op": "ListCategories"}` -### Testing with the WebSocket JavaScript API +#### Testing with the WebSocket JavaScript API [WebSocket JavaScript API](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) ```javascript @@ -171,6 +216,32 @@ ws.onopen = function () { })); }; ``` +### HTTP + +Endpoints are at <code>http://***host***/api/v1/***endpoint***</code>. They'll be listed below for each action. + +#### Testing with Curl + +##### Get Example + +``` +curl /community/list?sort=Hot +``` + +##### Post Example + +``` +curl -i -H \ +"Content-Type: application/json" \ +-X POST \ +-d '{ + "comment_id": X, + "post_id": X, + "score": X, + "auth": "..." +}' \ +/comment/like +``` ## Rate limits @@ -201,6 +272,11 @@ These go wherever there is a `sort` field. The available sort types are: - `TopYear` - the most upvoted posts/communities of the current year. - `TopAll` - the most upvoted posts/communities on the current instance. +### Websocket vs HTTP + +- Below are the websocket JSON requests / responses. For HTTP, ignore all fields except those inside `data`. +- For example, an http login will be a `POST` `{username_or_email: X, password: X}` + ### User / Authentication / Admin actions #### Login @@ -220,13 +296,19 @@ The `jwt` string should be stored and used anywhere `auth` is called for. ##### Response ```rust { - op: String, - jwt: String + op: "Login", + data: { + jwt: String, + } } ``` +##### HTTP + +`POST /user/login` #### Register + Only the first user will be able to be the admin. ##### Request @@ -245,11 +327,17 @@ Only the first user will be able to be the admin. ##### Response ```rust { - op: String, - jwt: String + op: "Register", + data: { + jwt: String, + } } ``` +##### HTTP + +`POST /user/register` + #### Get User Details ##### Request ```rust @@ -270,14 +358,20 @@ Only the first user will be able to be the admin. ##### Response ```rust { - op: String, - user: UserView, - follows: Vec<CommunityFollowerView>, - moderates: Vec<CommunityModeratorView>, - comments: Vec<CommentView>, - posts: Vec<PostView>, + op: "GetUserDetails", + data: { + user: UserView, + follows: Vec<CommunityFollowerView>, + moderates: Vec<CommunityModeratorView>, + comments: Vec<CommentView>, + posts: Vec<PostView>, + } } ``` +##### HTTP + +`GET /user` + #### Save User Settings ##### Request ```rust @@ -295,10 +389,16 @@ Only the first user will be able to be the admin. ##### Response ```rust { - op: String, - jwt: String + op: "SaveUserSettings", + data: { + jwt: String + } } ``` +##### HTTP + +`PUT /save_user_settings` + #### Get Replies / Inbox ##### Request ```rust @@ -316,10 +416,16 @@ Only the first user will be able to be the admin. ##### Response ```rust { - op: String, - replies: Vec<ReplyView>, + op: "GetReplies", + data: { + replies: Vec<ReplyView>, + } } ``` +##### HTTP + +`GET /user/replies` + #### Get User Mentions ##### Request @@ -338,10 +444,41 @@ Only the first user will be able to be the admin. ##### Response ```rust { - op: String, - mentions: Vec<UserMentionView>, + op: "GetUserMentions", + data: { + mentions: Vec<UserMentionView>, + } +} +``` + +##### HTTP + +`GET /user/mentions` + +#### Edit User Mention +##### Request +```rust +{ + op: "EditUserMention", + data: { + user_mention_id: i32, + read: Option<bool>, + auth: String, + } +} +``` +##### Response +```rust +{ + op: "EditUserMention", + data: { + mention: UserMentionView, + } } ``` +##### HTTP + +`PUT /user/mention` #### Mark All As Read @@ -359,11 +496,17 @@ Marks all user replies and mentions as read. ##### Response ```rust { - op: String, - replies: Vec<ReplyView>, + op: "MarkAllAsRead", + data: { + replies: Vec<ReplyView>, + } } ``` +##### HTTP + +`POST /user/mark_all_as_read` + #### Delete Account *Permananently deletes your posts and comments* @@ -381,11 +524,17 @@ Marks all user replies and mentions as read. ##### Response ```rust { - op: String, - jwt: String, + op: "DeleteAccount", + data: { + jwt: String, + } } ``` +##### HTTP + +`POST /user/delete_account` + #### Add admin ##### Request ```rust @@ -401,10 +550,15 @@ Marks all user replies and mentions as read. ##### Response ```rust { - op: String, - admins: Vec<UserView>, + op: "AddAdmin", + data: { + admins: Vec<UserView>, + } } ``` +##### HTTP + +`POST /admin/add` #### Ban user ##### Request @@ -423,11 +577,16 @@ Marks all user replies and mentions as read. ##### Response ```rust { - op: String, - user: UserView, - banned: bool, + op: "BanUser", + data: { + user: |