Updating API docs.

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)

docs/src/contributing_websocket_http_api.md

@@ -5,126 +5,171 @@
 
 - [Data types](#data-types)
 - [Basic usage](#basic-usage)
-  * [WebSocket Endpoint](#websocket-endpoint)
+  * [WebSocket](#websocket)
-  * [Testing with Websocat](#testing-with-websocat)
+    + [Testing with Websocat](#testing-with-websocat)
-  * [Testing with the WebSocket JavaScript API](#testing-with-the-websocket-javascript-api)
+    + [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)
+      - [HTTP](#http-10)
-    + [List Categories](#list-categories)
+    + [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)
+      - [HTTP](#http-17)
-    + [Get Community](#get-community)
+    + [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)
+      - [HTTP](#http-26)
-    + [Create Post](#create-post)
+    + [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)
+      - [HTTP](#http-32)
-    + [Create Comment](#create-comment)
+    + [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,
+  pub post_id: X,
+  score: X,
+  auth: X,
+}' \
+/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,
+  op: "Login",
-  jwt: String
+  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,
+  op: "Register",
-  jwt: String
+  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,
+  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,
+  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,
+  op: "GetReplies",
+  data: {
     replies: Vec<ReplyView>,
   }
+}
 ```
+##### HTTP
+
+`GET /user/replies`
+
 
 #### Get User Mentions
 ##### Request
@@ -338,11 +444,42 @@ Only the first user will be able to be the admin.
 ##### Response
 ```rust
 {
-  op: String,
+  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
 
 Marks all user replies and mentions as read.
@@ -359,11 +496,17 @@ Marks all user replies and mentions as read.
 ##### Response
 ```rust
 {
-  op: String,
+  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,
+  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,
+  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,
+  op: "BanUser",
+  data: {
     user: UserView,
     banned: bool,
   }
+}
 ```
+##### HTTP
+
+`POST /user/ban`
 
 ### Site
 #### List Categories
@@ -440,12 +599,18 @@ Marks all user replies and mentions as read.
 ##### Response
 ```rust
 {
-  op: String,
+  op: "ListCategories",
+  data: {
     categories: Vec<Category>
   }
+}
 ```
+##### HTTP
+
+`GET /categories`
 
 #### Search
+
 Search types are `Both, Comments, Posts`.
 
 ##### Request
@@ -465,11 +630,16 @@ Search types are `Both, Comments, Posts`.
 ##### Response
 ```rust
 {
-  op: String,
+  op: "Search",
+  data: {
     comments: Vec<CommentView>,
     posts: Vec<PostView>,
   }
+}
 ```
+##### HTTP
+
+`POST /search`
 
 #### Get Modlog
 ##### Request
@@ -487,7 +657,8 @@ Search types are `Both, Comments, Posts`.
 ##### Response
 ```rust
 {
-  op: String,
+  op: "GetModlog",
+  data: {
     removed_posts: Vec<ModRemovePostView>,
     locked_posts: Vec<ModLockPostView>,
     removed_comments: Vec<ModRemoveCommentView>,
@@ -497,8 +668,13 @@ Search types are `Both, Comments, Posts`.
     added_to_community: Vec<ModAddCommunityView>,
     added: Vec<ModAddView>,
   }
+}
 ```
 
+##### HTTP
+
+`GET /modlog`
+
 #### Create Site
 ##### Request
 ```rust
@@ -514,11 +690,17 @@ Search types are `Both, Comments, Posts`.
 ##### Response
 ```rust
 {
-  op: String,
+  op: "CreateSite",
+    data: {
     site: SiteView,
   }
+}
 ```
 
+##### HTTP
+
+`POST /site`
+
 #### Edit Site
 ##### Request
 ```rust
@@ -534,10 +716,15 @@ Search types are `Both, Comments, Posts`.
 ##### Response
 ```rust
 {
-  op: String,
+  op: "EditSite",
+  data: {
     site: SiteView,
   }
+}
 ```
+##### HTTP
+
+`PUT /site`
 
 #### Get Site
 ##### Request
@@ -549,12 +736,17 @@ Search types are `Both, Comments, Posts`.
 ##### Response
 ```rust
 {
-  op: String,
+  op: "GetSite",
+  data: {
     site: Option<SiteView>,
     admins: Vec<UserView>,
     banned: Vec<UserView>,
   }
+}
 ```
+##### HTTP
+
+`GET /site`
 
 #### Transfer Site
 ##### Request
@@ -570,12 +762,17 @@ Search types are `Both, Comments, Posts`.
 ##### Response
 ```rust
 {
-  op: String,
+  op: "TransferSite",
+  data: {
     site: Option<SiteView>,
     admins: Vec<UserView>,
     banned: Vec<UserView>,
   }
+}
 ```
+##### HTTP
+
+`POST /site/transfer`
 
 ### Community
 #### Get Community
@@ -593,12 +790,17 @@ Search types are `Both, Comments, Posts`.
 ##### Response
 ```rust
 {
-  op: String,
+  op: "GetCommunity",
+  data: {
     community: CommunityView,
     moderators: Vec<CommunityModeratorView>,
     admins: Vec<UserView>,
   }
+}
 ```
+##### HTTP
+
+`GET /community`
 
 #### Create Community
 ##### Request
@@ -617,10 +819,15 @@ Search types are `Both, Comments, Posts`.
 ##### Response
 ```rust
 {
-  op: String,
+  op: "CreateCommunity",
+  data: {
     community: CommunityView
   }
+}
 ```
+##### HTTP
+
+`POST /community`
 
 #### List Communities
 ##### Request
@@ -638,10 +845,15 @@ Search types are `Both, Comments, Posts`.
 ##### Response
 ```rust
 {
-  op: String,
+  op: "ListCommunities",
+  data: {
     communities: Vec<CommunityView>
   }
+}
 ```
+##### HTTP
+
+`GET /community/list`
 
 #### Ban from Community
 ##### Request
@@ -661,11 +873,16 @@ Search types are `Both, Comments, Posts`.
 ##### Response
 ```rust
 {
-  op: String,
+  op: "BanFromCommunity",
+  data: {
     user: UserView,
     banned: bool,
   }
+}
 ```
+##### HTTP
+
+`POST /community/ban_user`
 
 #### Add Mod to Community
 ##### Request
@@ -683,10 +900,15 @@ Search types are `Both, Comments, Posts`.
 ##### Response
 ```rust
 {
-  op: String,
+  op: "AddModToCommunity",
+  data: {
     moderators: Vec<CommunityModeratorView>,
   }
+}
 ```
+##### HTTP
+
+`POST /community/mod`
 
 #### Edit Community
 Mods and admins can remove and lock a community, creators can delete it.
@@ -712,10 +934,15 @@ Mods and admins can remove and lock a community, creators can delete it.
 ##### Response
 ```rust
 {
-  op: String,
+  op: "EditCommunity",
+  data: {
     community: CommunityView
   }
+}
 ```
+##### HTTP
+
+`PUT /community`
 
 #### Follow Community
 ##### Request
@@ -732,10 +959,15 @@ Mods and admins can remove and lock a community, creators can delete it.
 ##### Response
 ```rust
 {
-  op: String,
+  op: "FollowCommunity",
+  data: {
     community: CommunityView
   }
+}
 ```
+##### HTTP
+
+`POST /community/follow`
 
 #### Get Followed Communities
 ##### Request
@@ -750,10 +982,15 @@ Mods and admins can remove and lock a community, creators can delete it.
 ##### Response
 ```rust
 {
-  op: String,
+  op: "GetFollowedCommunities",
+  data: {
     communities: Vec<CommunityFollowerView>
   }
+}
 ```
+##### HTTP
+
+`GET /user/followed_communities`
 
 #### Transfer Community
 ##### Request
@@ -770,12 +1007,17 @@ Mods and admins can remove and lock a community, creators can delete it.
 ##### Response
 ```rust
 {
-  op: String,
+  op: "TransferCommunity",
+  data: {
     community: CommunityView,
     moderators: Vec<CommunityModeratorView>,
     admins: Vec<UserView>,
   }
+}
 ```
+##### HTTP
+
+`POST /community/transfer`
 
 ### Post
 #### Create Post
@@ -795,10 +1037,15 @@ Mods and admins can remove and lock a community, creators can delete it.
 ##### Response
 ```rust
 {
-  op: String,
+  op: "CreatePost",
+  data: {
     post: PostView
   }
+}
 ```
+##### HTTP
+
+`POST /post`
 
 #### Get Post
 ##### Request
@@ -814,16 +1061,22 @@ Mods and admins can remove and lock a community, creators can delete it.
 ##### Response
 ```rust
 {
-  op: String,
+  op: "GetPost",
+  data: {
     post: PostView,
     comments: Vec<CommentView>,
     community: CommunityView,
     moderators: Vec<CommunityModeratorView>,
     admins: Vec<UserView>,
   }
+}
 ```
+##### HTTP
+
+`GET /post`
 
 #### Get Posts
+
 Post listing types are `All, Subscribed, Community`
 
 ##### Request
@@ -843,12 +1096,18 @@ Post listing types are `All, Subscribed, Community`
 ##### Response
 ```rust
 {
-  op: String,
+  op: "GetPosts",
+  data: {
     posts: Vec<PostView>,
   }
+}
 ```
+##### HTTP
+
+`GET /post/list`
 
 #### Create Post Like
+
 `score` can be 0, -1, or 1
 
 ##### Request
@@ -865,12 +1124,18 @@ Post listing types are `All, Subscribed, Community`
 ##### Response
 ```rust
 {
-  op: String,
+  op: "CreatePostLike",
+  data: {
     post: PostView
   }
+}
 ```
+##### HTTP
+
+`POST /post/like`
 
 #### Edit Post
+
 Mods and admins can remove and lock a post, creators can delete it.
 
 ##### Request
@@ -895,11 +1160,17 @@ Mods and admins can remove and lock a post, creators can delete it.
 ##### Response
 ```rust
 {
-  op: String,
+  op: "EditPost",
+  data: {
     post: PostView
   }
+}
 ```
 
+##### HTTP
+
+`PUT /post`
+
 #### Save Post
 ##### Request
 ```rust
@@ -915,10 +1186,15 @@ Mods and admins can remove and lock a post, creators can delete it.
 ##### Response
 ```rust
 {
-  op: String,
+  op: "SavePost",
+  data: {
     post: PostView
   }
+}
 ```
+##### HTTP
+
+`POST /post/save`
 
 ### Comment
 #### Create Comment
@@ -938,12 +1214,19 @@ Mods and admins can remove and lock a post, creators can delete it.
 ##### Response
 ```rust
 {
-  op: String,
+  op: "CreateComment",
+  data: {
     comment: CommentView
   }
+}
 ```
 
+##### HTTP
+
+`POST /comment`
+
 #### Edit Comment
+
 Mods and admins can remove a comment, creators can delete it.
 
 ##### Request
@@ -967,10 +1250,15 @@ Mods and admins can remove a comment, creators can delete it.
 ##### Response
 ```rust
 {
-  op: String,
+  op: "EditComment",
+  data: {
     comment: CommentView
   }
+}
 ```
+##### HTTP
+
+`PUT /comment`
 
 #### Save Comment
 ##### Request
@@ -987,12 +1275,18 @@ Mods and admins can remove a comment, creators can delete it.
 ##### Response
 ```rust
 {
-  op: String,
+  op: "SaveComment",
+  data: {
     comment: CommentView
   }
+}
 ```
+##### HTTP
+
+`POST /comment/save`
 
 #### Create Comment Like
+
 `score` can be 0, -1, or 1
 
 ##### Request
@@ -1010,10 +1304,15 @@ Mods and admins can remove a comment, creators can delete it.
 ##### Response
 ```rust
 {
-  op: String,
+  op: "CreateCommentLike",
+  data: {
     comment: CommentView
   }
+}
 ```
+##### HTTP
+
+`POST /comment/like`
 
 ### RSS / Atom feeds