Merge pull request #29 from gazconroy/asyncapi

Made changes to reflect addition of asyncapi specification

src/en/SUMMARY.md

@@ -21,7 +21,7 @@
   - [Docker Development](contributing/docker_development.md)
   - [Local Development](contributing/local_development.md)
   - [Theming Guide](contributing/theming.md)
-  - [Websocket/HTTP API](contributing/websocket_http_api.md)
+  - [HTTP API](contributing/http_api.md)
   - [Creating a Custom Frontend](contributing/custom_frontend.md)
   - [Tests](contributing/tests.md)
   - [Federation Development](contributing/federation_development.md)

src/en/contributing/api_reference.md

@@ -0,0 +1,49 @@
+# API reference
+
+Lemmy has two, intertwined APIs:
+- [WebSocket](https://join.lemmy.ml/api/index.html)
+- [HTTP](http_api.md)
+
+This page describes concepts that are common to both.
+
+<!-- toc -->
+
+- [Basic usage](#basic-usage)
+- [Data types](#data-types)
+  * [Lemmy types](#lemmy-types)
+  * [Lower-level types](#lower-level-types)
+- [Default rate limits](#default-rate-limits)
+
+<!-- tocstop -->
+
+## Basic usage
+
+Request and response strings are in [JSON format](https://www.json.org).
+
+## Data types
+
+### Lemmy types
+
+- [Source tables, that have the columns / fields](https://github.com/LemmyNet/lemmy-js-client/blob/main/src/interfaces/source.ts)
+- [Aggregates (for things like scores)](https://github.com/LemmyNet/lemmy-js-client/blob/main/src/interfaces/aggregates.ts)
+- [Views - The main lemmy return types](https://github.com/LemmyNet/lemmy-js-client/blob/main/src/interfaces/views.ts)
+- [Request Forms / Responses are in this folder](https://github.com/LemmyNet/lemmy-js-client/tree/main/src/interfaces/api)
+
+### Lower-level types
+
+- `?` designates an option which may be omitted in requests and not be present in responses. It will be of type ***SomeType***.
+- `[SomeType]` is a list which contains objects of type ***SomeType***.
+- Times and dates are timestamp strings in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Timestamps will be UTC, your client must do the UTC to local conversion.
+
+## Default rate limits
+
+These can be edited in your `lemmy.hjson` file, by copying the relevant section from [defaults.hjson](https://github.com/LemmyNet/lemmy/blob/main/config/defaults.hjson).
+
+- 3 per hour for signups and community creation.
+- 6 per hour for image posting.
+- 6 per 10 minutes for post creation.
+- 180 actions per minute for post voting and comment creation.
+
+Everything else is not rate-limited.
+
+**See also:** [rate limiting for custom front-ends](custom_frontend.md#rate-limiting).

src/en/contributing/custom_frontend.md

@@ -1,6 +1,6 @@
 # Creating a Custom Frontend
 
-The backend and frontend are completely decoupled, and run in independent Docker containers. They only communicate over the [Lemmy API](websocket_http_api.md), which makes it quite easy to write alternative frontends.
+The backend and frontend are completely decoupled, and run in independent Docker containers. They only communicate over the [Lemmy API](api_reference.md), which makes it quite easy to write alternative frontends.
 
 This creates a lot of potential for custom frontends, which could change much of the design and user experience of Lemmy. For example, it would be possible to create a frontend in the style of a traditional forum like [phpBB](https://www.phpbb.com/), or a question-and-answer site like [stackoverflow](https://stackoverflow.com/). All without having to think about database queries, authentification or ActivityPub, which you essentially get for free.
 

src/en/contributing/http_api.md

@@ -0,0 +1,116 @@
+# Lemmy HTTP API
+
+
+<!-- toc -->
+
+- [Websocket vs HTTP API](#websocket-vs-http-api)
+- [Examples](#examples)
+  * [TypeScript](#typescript)
+  * [Curl](#curl)
+    + [GET](#get-example)
+    + [POST](#post-example)
+- [HTTP API exclusive features](#http-api-exclusive-features)
+  * [RSS/Atom feeds](#rss-atom-feeds)
+  * [Images](#images)
+    + [Create (request)](#create-request)
+    + [Create (response)](#create-response)
+    * [Delete](#delete)
+
+<!-- tocstop -->
+
+## WebSocket vs HTTP API
+Lemmy's HTTP API is almost identical to its WebSocket API:
+- **WebSocket API** needs `let send = { op: userOperation[op], data: form}` as shown in [the WebSocketAPI specification](add_link)
+- **HTTP API** needs the form (data) at the top level, an HTTP operation (GET, PUT or POST) and endpoint (at `http(s)://host/api/v2/endpoint`). For example:
+
+> `POST {username_or_email: X, password: X}`
+
+For more information, see the [http.ts](https://github.com/LemmyNet/lemmy-js-client/blob/main/src/http.ts) file.
+
+[The WebSocket API](Add_link) should be regarded as the primary source for the HTTP API since it also provides information about how to form HTTP API calls.
+
+## Examples
+
+### TypeScript
+
+```ts
+  async editComment(form: EditComment): Promise<CommentResponse> {
+  return this.wrapper(HttpType.Put, '/comment', form);
+  }
+```
+
+| Type | URL | Body type | Return type |
+| --- | --- | --- | --- |
+| `PUT` | `/comment` | `EditComment` | `CommentResponse` |
+
+### Curl
+
+**GET example**
+
+```
+curl "http://localhost:8536/api/v2/community/list?sort=Hot"`
+```
+
+**POST example**
+
+```
+curl -i -H \
+"Content-Type: application/json" \
+-X POST \
+-d '{
+  "comment_id": 374,
+  "score": 1,
+  "auth": eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6MiwiaXNzIjoidGVzdC5sZW1teS5tbCJ9.P77RX_kpz1a_geY5eCp29sl_5mAm-k27Cwnk8JcIZJk
+}' \
+http://localhost:8536/api/v2/comment/like
+```
+
+## HTTP API exclusive features
+
+These features cannot be accessed from the WebSocket API:
+
+- [RSS/Atom feeds](#rss-atom-feeds)
+- [Images](#images)
+
+### RSS/Atom feeds
+
+- All - `/feeds/all.xml?sort=Hot`
+- Community - `/feeds/c/community-name.xml?sort=Hot`
+- User - `/feeds/u/user-name.xml?sort=Hot`
+
+### Images
+
+Lemmy forwards image requests to a locally running Pictrs.
+
+`GET /pictrs/image/{filename}?format={webp, jpg, ...}&thumbnail={96}`
+
+*Format and thumbnail are optional.*
+
+#### Create (request)
+
+Uploaded content must be valid multipart/form-data with an image array located within the images[] key.
+
+`POST /pictrs/image` 
+
+#### Create (response)
+
+```
+{
+  "files": [
+    {
+      "delete_token": "{token}",
+      "file": "{file}.jpg"
+    }
+  ],
+  "msg": "ok"
+}
+```
+
+#### Delete
+
+`GET /pictrs/image/delete/{delete_token}/{file}`
+
+
+# Note
+
+This documentation may lag behind the actual [API endpoints](https://github.com/LemmyNet/lemmy-js-client/blob/main/src/http.ts) and the API itself should be considered unstable (since it may change at any time).

src/en/contributing/websocket_http_api.md

@@ -1,233 +0,0 @@
-# Lemmy API
-
-*Note: this may lag behind the actual API endpoints [here](https://github.com/LemmyNet/lemmy-js-client/blob/main/src/http.ts). The API should be considered unstable and may change any time.*
-
-<!-- toc -->
-
-- [Basic usage](#basic-usage)
-- [Data types](#data-types)
-  * [Lemmy Types](#lemmy-types)
-  * [Lower-level types](#lower-level-types)
-  * [Sort Types](#sort-types)
-- [Default Rate limits](#default-rate-limits)
-- [Errors](#errors)
-  * [Undoing actions](#undoing-actions)
-- [Websocket vs HTTP](#websocket-vs-http)
-- [HTTP](#http)
-  * [Example](#example)
-  * [Testing with Curl](#testing-with-curl)
-    + [Get Example](#get-example)
-    + [Post Example](#post-example)
-- [Websocket](#websocket)
-  * [Testing with Websocat](#testing-with-websocat)
-  * [Testing with the WebSocket JavaScript API](#testing-with-the-websocket-javascript-api)
-- [RSS / Atom feeds](#rss--atom-feeds)
-  * [All](#all)
-  * [Community](#community)
-  * [User](#user)
-- [Images](#images)
-  * [Get](#get)
-  * [Create](#create)
-    + [Request](#request)
-    + [Response](#response)
-  * [Delete](#delete)
-
-<!-- tocstop -->
-
-## Basic usage
-
-Request and response strings are in [JSON format](https://www.json.org).
-
-## Data types
-
-### Lemmy Types
-
-- [Source tables, that have the columns / fields](https://github.com/LemmyNet/lemmy-js-client/blob/main/src/interfaces/source.ts)
-- [Aggregates (for things like scores)](https://github.com/LemmyNet/lemmy-js-client/blob/main/src/interfaces/aggregates.ts)
-- [Views - The main lemmy return types](https://github.com/LemmyNet/lemmy-js-client/blob/main/src/interfaces/views.ts)
-- [Request Forms / Responses are in this folder](https://github.com/LemmyNet/lemmy-js-client/tree/main/src/interfaces/api)
-
-### Lower-level types
-
-- `?` designates an option which may be omitted in requests and not be present in responses. It will be of type ***SomeType***.
-- `[SomeType]` is a list which contains objects of type ***SomeType***.
-- The fields published, and updated are timestamp strings in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Timestamps will be UTC, your client must do the UTC -> local conversion.
-
-### Sort Types
-
-These go wherever there is a `sort` field. The available sort types are:
-
-- `Active` - the hottest posts/communities, depending on votes, and newest comment publish date.
-- `Hot` - the hottest posts/communities, depending on votes and publish date.
-- `New` - the newest posts/communities
-- `TopDay` - the most upvoted posts/communities of the current day.
-- `TopWeek` - the most upvoted posts/communities of the current week.
-- `TopMonth` - the most upvoted posts/communities of the current month.
-- `TopYear` - the most upvoted posts/communities of the current year.
-- `TopAll` - the most upvoted posts/communities on the current instance.
-
-## Default Rate limits
-
-These can be edited in your `lemmy.hjson` file, by copying the relevant section from [defaults.hjson](https://github.com/LemmyNet/lemmy/blob/main/config/defaults.hjson).
-
-- 3 per hour for signups and community creation.
-- 6 per hour for image posting.
-- 6 per 10 minutes for post creation.
-- 180 actions per minute for post voting and comment creation.
-- 
-- Everything else is not rate-limited.
-
-## Errors
-
-```rust
-{
-  op: String,
-  message: String,
-}
-```
-
-### Undoing actions
-
-Whenever you see a `deleted: bool`, `removed: bool`, `read: bool`, `locked: bool`, etc, you can undo this action by sending `false`:
-
-```ts
-// Un-delete a post
-let form: DeletePost = {
-  post_id: ...
-  deleted: false,
-  auth: ...
-}
-```
-
-## 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}`
-
-## HTTP 
-
-For documentation of the HTTP API, look at the [http.ts file in lemmy-js-client](https://github.com/LemmyNet/lemmy-js-client/blob/main/src/http.ts).
-
-Endpoints are at `http(s)://host/api/v2/endpoint`
-
-### Example
-
-```ts
-async editComment(form: EditComment): Promise<CommentResponse> {
-  return this.wrapper(HttpType.Put, '/comment', form);
-}
-```
-
-| Type | url | Body Type | Return Type |
-| --- | --- | --- | --- |
-| `PUT` | `/comment` | `EditComment` | `CommentResponse` |
-
-### Testing with Curl
-
-#### Get Example
-
-`curl "http://localhost:8536/api/v2/community/list?sort=Hot"`
-
-#### Post Example
-
-```
-curl -i -H \
-"Content-Type: application/json" \
--X POST \
--d '{
-  "comment_id": X,
-  "score": X,
-  "auth": X
-}' \
-http://localhost:8536/api/v2/comment/like
-```
-
-## Websocket
-
-The websocket commands are in [websocket.ts](https://github.com/LemmyNet/lemmy-js-client/blob/main/src/websocket.ts), and exactly match the http commands, 
-
-Connect to <code>ws://***host***/api/v2/ws</code> to get started.
-
-If the ***`host`*** supports secure connections, you can use <code>wss://***host***/api/v1/ws</code>.
-
-To receive websocket messages, you must join a room / context. The four available are:
-
-- UserJoin. Receives replies, private messages, etc.
-- PostJoin. Receives new comments on a post.
-- CommunityJoin. Receives front page / community posts.
-- ModJoin. Receives community moderator updates like reports.
-
-### Testing with Websocat
-
-[Websocat link](https://github.com/vi/websocat)
-
-`websocat ws://127.0.0.1:8536/api/v2/ws -nt`
-
-A simple test command:
-`{"op": "ListCategories", "data": {}}`
-
-### Testing with the WebSocket JavaScript API
-
-[WebSocket JavaScript API](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
-
-```javascript
-var ws = new WebSocket("ws://" + host + "/api/v2/ws");
-ws.onopen = function () {
-  console.log("Connection succeed!");
-  ws.send(JSON.stringify({
-    op: "ListCategories",
-    data: {}
-  }));
-};
-```
-
-## RSS / Atom feeds
-
-### All
-
-`/feeds/all.xml?sort=Hot`
-
-### Community
-
-`/feeds/c/community-name.xml?sort=Hot`
-
-### User
-
-`/feeds/u/user-name.xml?sort=Hot`
-
-## Images
-
-Lemmy forwards image requests to a locally running Pictrs.
-
-### Get
-
-*Format and thumbnail are optional.*
-
-`GET /pictrs/image/{filename}?format={webp, jpg, ...}&thumbnail={96}`
-
-### Create
-
-#### Request
-
-Uploaded content must be valid multipart/form-data with an image array located within the images[] key.
-
-`POST /pictrs/image` 
-
-#### Response
-
-```
-{
-  "files": [
-    {
-      "delete_token": "{token}",
-      "file": "{file}.jpg"
-    }
-  ],
-  "msg": "ok"
-}
-```
-
-### Delete
-
-`GET /pictrs/image/delete/{delete_token}/{file}`
-