3 *Note: this may lag behind the actual API endpoints [here](../server/src/api).*
7 - [Data types](#data-types)
8 - [Basic usage](#basic-usage)
9 * [WebSocket](#websocket)
10 + [Testing with Websocat](#testing-with-websocat)
11 + [Testing with the WebSocket JavaScript API](#testing-with-the-websocket-javascript-api)
13 + [Testing with Curl](#testing-with-curl)
14 - [Get Example](#get-example)
15 - [Post Example](#post-example)
16 - [Rate limits](#rate-limits)
18 - [API documentation](#api-documentation)
19 * [Sort Types](#sort-types)
20 * [Websocket vs HTTP](#websocket-vs-http)
21 * [User / Authentication / Admin actions](#user--authentication--admin-actions)
24 - [Response](#response)
26 + [Register](#register)
27 - [Request](#request-1)
28 - [Response](#response-1)
30 + [Get User Details](#get-user-details)
31 - [Request](#request-2)
32 - [Response](#response-2)
34 + [Save User Settings](#save-user-settings)
35 - [Request](#request-3)
36 - [Response](#response-3)
38 + [Get Replies / Inbox](#get-replies--inbox)
39 - [Request](#request-4)
40 - [Response](#response-4)
42 + [Get User Mentions](#get-user-mentions)
43 - [Request](#request-5)
44 - [Response](#response-5)
46 + [Edit User Mention](#edit-user-mention)
47 - [Request](#request-6)
48 - [Response](#response-6)
50 + [Mark All As Read](#mark-all-as-read)
51 - [Request](#request-7)
52 - [Response](#response-7)
54 + [Delete Account](#delete-account)
55 - [Request](#request-8)
56 - [Response](#response-8)
58 + [Add admin](#add-admin)
59 - [Request](#request-9)
60 - [Response](#response-9)
62 + [Ban user](#ban-user)
63 - [Request](#request-10)
64 - [Response](#response-10)
67 + [List Categories](#list-categories)
68 - [Request](#request-11)
69 - [Response](#response-11)
72 - [Request](#request-12)
73 - [Response](#response-12)
75 + [Get Modlog](#get-modlog)
76 - [Request](#request-13)
77 - [Response](#response-13)
79 + [Create Site](#create-site)
80 - [Request](#request-14)
81 - [Response](#response-14)
83 + [Edit Site](#edit-site)
84 - [Request](#request-15)
85 - [Response](#response-15)
87 + [Get Site](#get-site)
88 - [Request](#request-16)
89 - [Response](#response-16)
91 + [Transfer Site](#transfer-site)
92 - [Request](#request-17)
93 - [Response](#response-17)
95 * [Community](#community)
96 + [Get Community](#get-community)
97 - [Request](#request-18)
98 - [Response](#response-18)
100 + [Create Community](#create-community)
101 - [Request](#request-19)
102 - [Response](#response-19)
104 + [List Communities](#list-communities)
105 - [Request](#request-20)
106 - [Response](#response-20)
108 + [Ban from Community](#ban-from-community)
109 - [Request](#request-21)
110 - [Response](#response-21)
112 + [Add Mod to Community](#add-mod-to-community)
113 - [Request](#request-22)
114 - [Response](#response-22)
116 + [Edit Community](#edit-community)
117 - [Request](#request-23)
118 - [Response](#response-23)
120 + [Follow Community](#follow-community)
121 - [Request](#request-24)
122 - [Response](#response-24)
124 + [Get Followed Communities](#get-followed-communities)
125 - [Request](#request-25)
126 - [Response](#response-25)
128 + [Transfer Community](#transfer-community)
129 - [Request](#request-26)
130 - [Response](#response-26)
133 + [Create Post](#create-post)
134 - [Request](#request-27)
135 - [Response](#response-27)
137 + [Get Post](#get-post)
138 - [Request](#request-28)
139 - [Response](#response-28)
141 + [Get Posts](#get-posts)
142 - [Request](#request-29)
143 - [Response](#response-29)
145 + [Create Post Like](#create-post-like)
146 - [Request](#request-30)
147 - [Response](#response-30)
149 + [Edit Post](#edit-post)
150 - [Request](#request-31)
151 - [Response](#response-31)
153 + [Save Post](#save-post)
154 - [Request](#request-32)
155 - [Response](#response-32)
157 * [Comment](#comment)
158 + [Create Comment](#create-comment)
159 - [Request](#request-33)
160 - [Response](#response-33)
162 + [Edit Comment](#edit-comment)
163 - [Request](#request-34)
164 - [Response](#response-34)
166 + [Save Comment](#save-comment)
167 - [Request](#request-35)
168 - [Response](#response-35)
170 + [Create Comment Like](#create-comment-like)
171 - [Request](#request-36)
172 - [Response](#response-36)
174 * [RSS / Atom feeds](#rss--atom-feeds)
176 + [Community](#community-1)
183 - `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.
184 - <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***.
185 - <code>Vec<***SomeType***></code> is a list which contains objects of type ***SomeType***.
186 - `chrono::NaiveDateTime` is a timestamp string in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Timestamps will be UTC.
187 - Other data types are listed [here](../server/src/db).
191 Request and response strings are in [JSON format](https://www.json.org).
195 Connect to <code>ws://***host***/api/v1/ws</code> to get started.
197 If the ***`host`*** supports secure connections, you can use <code>wss://***host***/api/v1/ws</code>.
199 #### Testing with Websocat
201 [Websocat link](https://github.com/vi/websocat)
203 `websocat ws://127.0.0.1:8536/api/v1/ws -nt`
205 A simple test command:
206 `{"op": "ListCategories"}`
208 #### Testing with the WebSocket JavaScript API
210 [WebSocket JavaScript API](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
212 var ws = new WebSocket("ws://" + host + "/api/v1/ws");
213 ws.onopen = function () {
214 console.log("Connection succeed!");
215 ws.send(JSON.stringify({
222 Endpoints are at <code>http://***host***/api/v1/***endpoint***</code>. They'll be listed below for each action.
224 #### Testing with Curl
229 curl /community/list?sort=Hot
236 "Content-Type: application/json" \
249 - 1 per hour for signups and community creation.
250 - 1 per 10 minutes for post creation.
251 - 30 actions per minute for post voting and comment creation.
252 - Everything else is not rate-limited.
266 These go wherever there is a `sort` field. The available sort types are:
268 - `Hot` - the hottest posts/communities, depending on votes, views, comments and publish date
269 - `New` - the newest posts/communities
270 - `TopDay` - the most upvoted posts/communities of the current day.
271 - `TopWeek` - the most upvoted posts/communities of the current week.
272 - `TopMonth` - the most upvoted posts/communities of the current month.
273 - `TopYear` - the most upvoted posts/communities of the current year.
274 - `TopAll` - the most upvoted posts/communities on the current instance.
276 ### Websocket vs HTTP
278 - Below are the websocket JSON requests / responses. For HTTP, ignore all fields except those inside `data`.
279 - For example, an http login will be a `POST` `{username_or_email: X, password: X}`
281 ### User / Authentication / Admin actions
285 The `jwt` string should be stored and used anywhere `auth` is called for.
292 username_or_email: String,
313 Only the first user will be able to be the admin.
321 email: Option<String>,
323 password_verify: String,
340 `POST /user/register`
342 #### Get User Details
346 op: "GetUserDetails",
348 user_id: Option<i32>,
349 username: Option<String>,
353 community_id: Option<i32>,
355 auth: Option<String>,
362 op: "GetUserDetails",
365 follows: Vec<CommunityFollowerView>,
366 moderates: Vec<CommunityModeratorView>,
367 comments: Vec<CommentView>,
368 posts: Vec<PostView>,
376 #### Save User Settings
380 op: "SaveUserSettings",
383 theme: String, // Default 'darkly'
384 default_sort_type: i16, // The Sort types from above, zero indexed as a number
385 default_listing_type: i16, // Post listing types are `All, Subscribed, Community`
393 op: "SaveUserSettings",
401 `PUT /save_user_settings`
403 #### Get Replies / Inbox
422 replies: Vec<ReplyView>,
431 #### Get User Mentions
435 op: "GetUserMentions",
448 op: "GetUserMentions",
450 mentions: Vec<UserMentionView>,
459 #### Edit User Mention
463 op: "EditUserMention",
465 user_mention_id: i32,
474 op: "EditUserMention",
476 mention: UserMentionView,
484 #### Mark All As Read
486 Marks all user replies and mentions as read.
502 replies: Vec<ReplyView>,
509 `POST /user/mark_all_as_read`
513 *Permananently deletes your posts and comments*
537 `POST /user/delete_account`
556 admins: Vec<UserView>,
572 reason: Option<String>,
573 expires: Option<i64>,
603 op: "ListCategories",
605 categories: Vec<Category>
615 Search types are `All, Comments, Posts, Communities, Users, Url`
624 community_id: Option<i32>,
628 auth?: Option<String>,
638 comments: Vec<CommentView>,
639 posts: Vec<PostView>,
640 communities: Vec<CommunityView>,
641 users: Vec<UserView>,
655 mod_user_id: Option<i32>,
656 community_id: Option<i32>,
667 removed_posts: Vec<ModRemovePostView>,
668 locked_posts: Vec<ModLockPostView>,
669 removed_comments: Vec<ModRemoveCommentView>,
670 removed_communities: Vec<ModRemoveCommunityView>,
671 banned_from_community: Vec<ModBanFromCommunityView>,
672 banned: Vec<ModBanView>,
673 added_to_community: Vec<ModAddCommunityView>,
674 added: Vec<ModAddView>,
690 description: Option<String>,
716 description: Option<String>,
746 site: Option<SiteView>,
747 admins: Vec<UserView>,
748 banned: Vec<UserView>,
772 site: Option<SiteView>,
773 admins: Vec<UserView>,
774 banned: Vec<UserView>,
780 `POST /site/transfer`
790 name: Option<String>,
800 community: CommunityView,
801 moderators: Vec<CommunityModeratorView>,
802 admins: Vec<UserView>,
810 #### Create Community
814 op: "CreateCommunity",
818 description: Option<String>,
827 op: "CreateCommunity",
829 community: CommunityView
837 #### List Communities
841 op: "ListCommunities",
853 op: "ListCommunities",
855 communities: Vec<CommunityView>
861 `GET /community/list`
863 #### Ban from Community
867 op: "BanFromCommunity",
872 reason: Option<String>,
873 expires: Option<i64>,
881 op: "BanFromCommunity",
890 `POST /community/ban_user`
892 #### Add Mod to Community
896 op: "AddModToCommunity",
908 op: "AddModToCommunity",
910 moderators: Vec<CommunityModeratorView>,
916 `POST /community/mod`
919 Mods and admins can remove and lock a community, creators can delete it.
929 description: Option<String>,
931 removed: Option<bool>,
932 deleted: Option<bool>,
933 reason: Option<String>,
934 expires: Option<i64>,
944 community: CommunityView
952 #### Follow Community
956 op: "FollowCommunity",
967 op: "FollowCommunity",
969 community: CommunityView
975 `POST /community/follow`
977 #### Get Followed Communities
981 op: "GetFollowedCommunities",
990 op: "GetFollowedCommunities",
992 communities: Vec<CommunityFollowerView>
998 `GET /user/followed_communities`
1000 #### Transfer Community
1004 op: "TransferCommunity",
1015 op: "TransferCommunity",
1017 community: CommunityView,
1018 moderators: Vec<CommunityModeratorView>,
1019 admins: Vec<UserView>,
1025 `POST /community/transfer`
1035 url: Option<String>,
1036 body: Option<String>,
1062 auth: Option<String>
1072 comments: Vec<CommentView>,
1073 community: CommunityView,
1074 moderators: Vec<CommunityModeratorView>,
1075 admins: Vec<UserView>,
1085 Post listing types are `All, Subscribed, Community`
1096 community_id: Option<i32>,
1097 auth: Option<String>
1106 posts: Vec<PostView>,
1114 #### Create Post Like
1116 `score` can be 0, -1, or 1
1121 op: "CreatePostLike",
1132 op: "CreatePostLike",
1144 Mods and admins can remove and lock a post, creators can delete it.
1155 url: Option<String>,
1156 body: Option<String>,
1157 removed: Option<bool>,
1158 deleted: Option<bool>,
1159 locked: Option<bool>,
1160 reason: Option<String>,
1209 op: "CreateComment",
1212 parent_id: Option<i32>,
1213 edit_id: Option<i32>,
1222 op: "CreateComment",
1224 comment: CommentView
1235 Mods and admins can remove a comment, creators can delete it.
1243 parent_id: Option<i32>,
1247 removed: Option<bool>,
1248 deleted: Option<bool>,
1249 reason: Option<String>,
1260 comment: CommentView
1285 comment: CommentView
1291 `POST /comment/save`
1293 #### Create Comment Like
1295 `score` can be 0, -1, or 1
1300 op: "CreateCommentLike",
1312 op: "CreateCommentLike",
1314 comment: CommentView
1320 `POST /comment/like`
1322 ### RSS / Atom feeds
1326 `/feeds/all.xml?sort=Hot`
1330 `/feeds/c/community-name.xml?sort=Hot`
1334 `/feeds/u/user-name.xml?sort=Hot`