2 *Note: this may lag behind the actual API endpoints [here](../server/src/api).*
6 - [Data types](#data-types)
7 - [Basic usage](#basic-usage)
8 * [WebSocket](#websocket)
9 + [Testing with Websocat](#testing-with-websocat)
10 + [Testing with the WebSocket JavaScript API](#testing-with-the-websocket-javascript-api)
12 + [Testing with Curl](#testing-with-curl)
13 - [Get Example](#get-example)
14 - [Post Example](#post-example)
15 - [Rate limits](#rate-limits)
17 - [API documentation](#api-documentation)
18 * [Sort Types](#sort-types)
19 * [Websocket vs HTTP](#websocket-vs-http)
20 * [User / Authentication / Admin actions](#user--authentication--admin-actions)
23 - [Response](#response)
25 + [Register](#register)
26 - [Request](#request-1)
27 - [Response](#response-1)
29 + [Get User Details](#get-user-details)
30 - [Request](#request-2)
31 - [Response](#response-2)
33 + [Save User Settings](#save-user-settings)
34 - [Request](#request-3)
35 - [Response](#response-3)
37 + [Get Replies / Inbox](#get-replies--inbox)
38 - [Request](#request-4)
39 - [Response](#response-4)
41 + [Get User Mentions](#get-user-mentions)
42 - [Request](#request-5)
43 - [Response](#response-5)
45 + [Edit User Mention](#edit-user-mention)
46 - [Request](#request-6)
47 - [Response](#response-6)
49 + [Mark All As Read](#mark-all-as-read)
50 - [Request](#request-7)
51 - [Response](#response-7)
53 + [Delete Account](#delete-account)
54 - [Request](#request-8)
55 - [Response](#response-8)
57 + [Add admin](#add-admin)
58 - [Request](#request-9)
59 - [Response](#response-9)
61 + [Ban user](#ban-user)
62 - [Request](#request-10)
63 - [Response](#response-10)
66 + [List Categories](#list-categories)
67 - [Request](#request-11)
68 - [Response](#response-11)
71 - [Request](#request-12)
72 - [Response](#response-12)
74 + [Get Modlog](#get-modlog)
75 - [Request](#request-13)
76 - [Response](#response-13)
78 + [Create Site](#create-site)
79 - [Request](#request-14)
80 - [Response](#response-14)
82 + [Edit Site](#edit-site)
83 - [Request](#request-15)
84 - [Response](#response-15)
86 + [Get Site](#get-site)
87 - [Request](#request-16)
88 - [Response](#response-16)
90 + [Transfer Site](#transfer-site)
91 - [Request](#request-17)
92 - [Response](#response-17)
94 * [Community](#community)
95 + [Get Community](#get-community)
96 - [Request](#request-18)
97 - [Response](#response-18)
99 + [Create Community](#create-community)
100 - [Request](#request-19)
101 - [Response](#response-19)
103 + [List Communities](#list-communities)
104 - [Request](#request-20)
105 - [Response](#response-20)
107 + [Ban from Community](#ban-from-community)
108 - [Request](#request-21)
109 - [Response](#response-21)
111 + [Add Mod to Community](#add-mod-to-community)
112 - [Request](#request-22)
113 - [Response](#response-22)
115 + [Edit Community](#edit-community)
116 - [Request](#request-23)
117 - [Response](#response-23)
119 + [Follow Community](#follow-community)
120 - [Request](#request-24)
121 - [Response](#response-24)
123 + [Get Followed Communities](#get-followed-communities)
124 - [Request](#request-25)
125 - [Response](#response-25)
127 + [Transfer Community](#transfer-community)
128 - [Request](#request-26)
129 - [Response](#response-26)
132 + [Create Post](#create-post)
133 - [Request](#request-27)
134 - [Response](#response-27)
136 + [Get Post](#get-post)
137 - [Request](#request-28)
138 - [Response](#response-28)
140 + [Get Posts](#get-posts)
141 - [Request](#request-29)
142 - [Response](#response-29)
144 + [Create Post Like](#create-post-like)
145 - [Request](#request-30)
146 - [Response](#response-30)
148 + [Edit Post](#edit-post)
149 - [Request](#request-31)
150 - [Response](#response-31)
152 + [Save Post](#save-post)
153 - [Request](#request-32)
154 - [Response](#response-32)
156 * [Comment](#comment)
157 + [Create Comment](#create-comment)
158 - [Request](#request-33)
159 - [Response](#response-33)
161 + [Edit Comment](#edit-comment)
162 - [Request](#request-34)
163 - [Response](#response-34)
165 + [Save Comment](#save-comment)
166 - [Request](#request-35)
167 - [Response](#response-35)
169 + [Create Comment Like](#create-comment-like)
170 - [Request](#request-36)
171 - [Response](#response-36)
173 * [RSS / Atom feeds](#rss--atom-feeds)
175 + [Community](#community-1)
182 - `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.
183 - <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***.
184 - <code>Vec<***SomeType***></code> is a list which contains objects of type ***SomeType***.
185 - `chrono::NaiveDateTime` is a timestamp string in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Timestamps will be UTC.
186 - Other data types are listed [here](../server/src/db).
190 Request and response strings are in [JSON format](https://www.json.org).
194 Connect to <code>ws://***host***/api/v1/ws</code> to get started.
196 If the ***`host`*** supports secure connections, you can use <code>wss://***host***/api/v1/ws</code>.
198 #### Testing with Websocat
200 [Websocat link](https://github.com/vi/websocat)
202 `websocat ws://127.0.0.1:8536/api/v1/ws -nt`
204 A simple test command:
205 `{"op": "ListCategories"}`
207 #### Testing with the WebSocket JavaScript API
209 [WebSocket JavaScript API](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
211 var ws = new WebSocket("ws://" + host + "/api/v1/ws");
212 ws.onopen = function () {
213 console.log("Connection succeed!");
214 ws.send(JSON.stringify({
221 Endpoints are at <code>http://***host***/api/v1/***endpoint***</code>. They'll be listed below for each action.
223 #### Testing with Curl
228 curl /community/list?sort=Hot
235 "Content-Type: application/json" \
248 - 1 per hour for signups and community creation.
249 - 1 per 10 minutes for post creation.
250 - 30 actions per minute for post voting and comment creation.
251 - Everything else is not rate-limited.
265 These go wherever there is a `sort` field. The available sort types are:
267 - `Hot` - the hottest posts/communities, depending on votes, views, comments and publish date
268 - `New` - the newest posts/communities
269 - `TopDay` - the most upvoted posts/communities of the current day.
270 - `TopWeek` - the most upvoted posts/communities of the current week.
271 - `TopMonth` - the most upvoted posts/communities of the current month.
272 - `TopYear` - the most upvoted posts/communities of the current year.
273 - `TopAll` - the most upvoted posts/communities on the current instance.
275 ### Websocket vs HTTP
277 - Below are the websocket JSON requests / responses. For HTTP, ignore all fields except those inside `data`.
278 - For example, an http login will be a `POST` `{username_or_email: X, password: X}`
280 ### User / Authentication / Admin actions
284 The `jwt` string should be stored and used anywhere `auth` is called for.
291 username_or_email: String,
312 Only the first user will be able to be the admin.
320 email: Option<String>,
322 password_verify: String,
339 `POST /user/register`
341 #### Get User Details
345 op: "GetUserDetails",
347 user_id: Option<i32>,
348 username: Option<String>,
352 community_id: Option<i32>,
354 auth: Option<String>,
361 op: "GetUserDetails",
364 follows: Vec<CommunityFollowerView>,
365 moderates: Vec<CommunityModeratorView>,
366 comments: Vec<CommentView>,
367 posts: Vec<PostView>,
375 #### Save User Settings
379 op: "SaveUserSettings",
382 theme: String, // Default 'darkly'
383 default_sort_type: i16, // The Sort types from above, zero indexed as a number
384 default_listing_type: i16, // Post listing types are `All, Subscribed, Community`
392 op: "SaveUserSettings",
400 `PUT /save_user_settings`
402 #### Get Replies / Inbox
421 replies: Vec<ReplyView>,
430 #### Get User Mentions
434 op: "GetUserMentions",
447 op: "GetUserMentions",
449 mentions: Vec<UserMentionView>,
458 #### Edit User Mention
462 op: "EditUserMention",
464 user_mention_id: i32,
473 op: "EditUserMention",
475 mention: UserMentionView,
483 #### Mark All As Read
485 Marks all user replies and mentions as read.
501 replies: Vec<ReplyView>,
508 `POST /user/mark_all_as_read`
512 *Permananently deletes your posts and comments*
536 `POST /user/delete_account`
555 admins: Vec<UserView>,
571 reason: Option<String>,
572 expires: Option<i64>,
602 op: "ListCategories",
604 categories: Vec<Category>
614 Search types are `All, Comments, Posts, Communities, Users, Url`
623 community_id: Option<i32>,
627 auth?: Option<String>,
637 comments: Vec<CommentView>,
638 posts: Vec<PostView>,
639 communities: Vec<CommunityView>,
640 users: Vec<UserView>,
654 mod_user_id: Option<i32>,
655 community_id: Option<i32>,
666 removed_posts: Vec<ModRemovePostView>,
667 locked_posts: Vec<ModLockPostView>,
668 removed_comments: Vec<ModRemoveCommentView>,
669 removed_communities: Vec<ModRemoveCommunityView>,
670 banned_from_community: Vec<ModBanFromCommunityView>,
671 banned: Vec<ModBanView>,
672 added_to_community: Vec<ModAddCommunityView>,
673 added: Vec<ModAddView>,
689 description: Option<String>,
715 description: Option<String>,
745 site: Option<SiteView>,
746 admins: Vec<UserView>,
747 banned: Vec<UserView>,
771 site: Option<SiteView>,
772 admins: Vec<UserView>,
773 banned: Vec<UserView>,
779 `POST /site/transfer`
789 name: Option<String>,
799 community: CommunityView,
800 moderators: Vec<CommunityModeratorView>,
801 admins: Vec<UserView>,
809 #### Create Community
813 op: "CreateCommunity",
817 description: Option<String>,
826 op: "CreateCommunity",
828 community: CommunityView
836 #### List Communities
840 op: "ListCommunities",
852 op: "ListCommunities",
854 communities: Vec<CommunityView>
860 `GET /community/list`
862 #### Ban from Community
866 op: "BanFromCommunity",
871 reason: Option<String>,
872 expires: Option<i64>,
880 op: "BanFromCommunity",
889 `POST /community/ban_user`
891 #### Add Mod to Community
895 op: "AddModToCommunity",
907 op: "AddModToCommunity",
909 moderators: Vec<CommunityModeratorView>,
915 `POST /community/mod`
918 Mods and admins can remove and lock a community, creators can delete it.
928 description: Option<String>,
930 removed: Option<bool>,
931 deleted: Option<bool>,
932 reason: Option<String>,
933 expires: Option<i64>,
943 community: CommunityView
951 #### Follow Community
955 op: "FollowCommunity",
966 op: "FollowCommunity",
968 community: CommunityView
974 `POST /community/follow`
976 #### Get Followed Communities
980 op: "GetFollowedCommunities",
989 op: "GetFollowedCommunities",
991 communities: Vec<CommunityFollowerView>
997 `GET /user/followed_communities`
999 #### Transfer Community
1003 op: "TransferCommunity",
1014 op: "TransferCommunity",
1016 community: CommunityView,
1017 moderators: Vec<CommunityModeratorView>,
1018 admins: Vec<UserView>,
1024 `POST /community/transfer`
1034 url: Option<String>,
1035 body: Option<String>,
1061 auth: Option<String>
1071 comments: Vec<CommentView>,
1072 community: CommunityView,
1073 moderators: Vec<CommunityModeratorView>,
1074 admins: Vec<UserView>,
1084 Post listing types are `All, Subscribed, Community`
1095 community_id: Option<i32>,
1096 auth: Option<String>
1105 posts: Vec<PostView>,
1113 #### Create Post Like
1115 `score` can be 0, -1, or 1
1120 op: "CreatePostLike",
1131 op: "CreatePostLike",
1143 Mods and admins can remove and lock a post, creators can delete it.
1154 url: Option<String>,
1155 body: Option<String>,
1156 removed: Option<bool>,
1157 deleted: Option<bool>,
1158 locked: Option<bool>,
1159 reason: Option<String>,
1208 op: "CreateComment",
1211 parent_id: Option<i32>,
1212 edit_id: Option<i32>,
1221 op: "CreateComment",
1223 comment: CommentView
1234 Mods and admins can remove a comment, creators can delete it.
1242 parent_id: Option<i32>,
1246 removed: Option<bool>,
1247 deleted: Option<bool>,
1248 reason: Option<String>,
1259 comment: CommentView
1284 comment: CommentView
1290 `POST /comment/save`
1292 #### Create Comment Like
1294 `score` can be 0, -1, or 1
1299 op: "CreateCommentLike",
1311 op: "CreateCommentLike",
1313 comment: CommentView
1319 `POST /comment/like`
1321 ### RSS / Atom feeds
1325 `/feeds/all.xml?sort=Hot`
1329 `/feeds/c/community-name.xml?sort=Hot`
1333 `/feeds/u/user-name.xml?sort=Hot`