mirror of
https://github.com/LemmyNet/lemmy-docs.git
synced 2024-11-01 10:09:54 +00:00
Merge pull request #29 from gazconroy/asyncapi
Made changes to reflect addition of asyncapi specification
This commit is contained in:
Dessalines
GitHub
commit
847e6fecff
5 changed files with 167 additions and 235 deletions
|
|
@ -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)
|
||||
|
|
|
|||
49
src/en/contributing/api_reference.md
Normal file
49
src/en/contributing/api_reference.md
Normal file
|
|
@ -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).
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
116
src/en/contributing/http_api.md
Normal file
116
src/en/contributing/http_api.md
Normal file
|
|
@ -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).
|
||||
|
|
@ -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}`
|
||||
|
||||
Loading…
Reference in a new issue