mirror of
https://github.com/LemmyNet/lemmy-docs.git
synced 2024-11-21 20:01:10 +00:00
Fix/api docs typedoc (#94)
* Moving API docs to typedocs. Fixes #93 * Fix client dev. * Refer to API docs multiple times * Forgot to remove http_api.md file. * Fix an image issue.
This commit is contained in:
parent
089ddd39d8
commit
532b1c04ca
7 changed files with 87 additions and 175 deletions
|
@ -17,10 +17,8 @@
|
||||||
- [Federation Overview](federation/overview.md)
|
- [Federation Overview](federation/overview.md)
|
||||||
- [Lemmy Protocol](federation/lemmy_protocol.md)
|
- [Lemmy Protocol](federation/lemmy_protocol.md)
|
||||||
- [Client Development](client_development/client_development.md)
|
- [Client Development](client_development/client_development.md)
|
||||||
|
- [HTTP API extras](client_development/http_api_extras.md)
|
||||||
- [Theming Guide](client_development/theming.md)
|
- [Theming Guide](client_development/theming.md)
|
||||||
- [API reference](client_development/api_reference.md)
|
|
||||||
- [WebSocket API](client_development/websocket_api.md)
|
|
||||||
- [HTTP API](client_development/http_api.md)
|
|
||||||
- [Creating a Custom Frontend](client_development/custom_frontend.md)
|
- [Creating a Custom Frontend](client_development/custom_frontend.md)
|
||||||
- [Contributing](contributing/contributing.md)
|
- [Contributing](contributing/contributing.md)
|
||||||
- [Docker Development](contributing/docker_development.md)
|
- [Docker Development](contributing/docker_development.md)
|
||||||
|
|
|
@ -2,7 +2,7 @@
|
||||||
|
|
||||||
Front Page|Post
|
Front Page|Post
|
||||||
---|---
|
---|---
|
||||||
![main screen](main_screen.png)|![chat screen](chat_screen.png)
|
![main screen](/docs/en/about/main_screen.png)|![chat screen](/docs/en/about/chat_screen.png)
|
||||||
|
|
||||||
[Lemmy](https://github.com/LemmyNet/lemmy) is similar to sites like [Reddit](https://reddit.com), [Lobste.rs](https://lobste.rs), [Raddle](https://raddle.me), or [Hacker News](https://news.ycombinator.com/): you subscribe to forums you're interested in, post links and discussions, then vote, and comment on them. Behind the scenes, it is very different; anyone can easily run a server, and all these servers are federated (think email), and connected to the same universe, called the [Fediverse](https://en.wikipedia.org/wiki/Fediverse).
|
[Lemmy](https://github.com/LemmyNet/lemmy) is similar to sites like [Reddit](https://reddit.com), [Lobste.rs](https://lobste.rs), [Raddle](https://raddle.me), or [Hacker News](https://news.ycombinator.com/): you subscribe to forums you're interested in, post links and discussions, then vote, and comment on them. Behind the scenes, it is very different; anyone can easily run a server, and all these servers are federated (think email), and connected to the same universe, called the [Fediverse](https://en.wikipedia.org/wiki/Fediverse).
|
||||||
|
|
||||||
|
|
|
@ -1,49 +0,0 @@
|
||||||
# API reference
|
|
||||||
|
|
||||||
Lemmy has two, intertwined APIs:
|
|
||||||
- [WebSocket](https://join-lemmy.org/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,5 @@
|
||||||
# Client Development
|
# Client Development
|
||||||
|
|
||||||
- [Theming Guide](client_development/theming.md)
|
- [API docs](/api)
|
||||||
- [API reference](client_development/api_reference.md)
|
- [HTTP API extras](http_api_extras.md)
|
||||||
- [WebSocket API](https://join-lemmy.org/api/index.html)
|
- [Theming Guide](theming.md)
|
||||||
- [HTTP API](client_development/http_api.md)
|
|
||||||
|
|
|
@ -1,116 +0,0 @@
|
||||||
# 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](https://join-lemmy.org/api/index.html)
|
|
||||||
- **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](https://join-lemmy.org/api/index.html) 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).
|
|
82
src/en/client_development/http_api_extras.md
Normal file
82
src/en/client_development/http_api_extras.md
Normal file
|
@ -0,0 +1,82 @@
|
||||||
|
# Lemmy HTTP API Extras
|
||||||
|
|
||||||
|
This contains extras not in the [API docs](/api).
|
||||||
|
|
||||||
|
<!-- toc -->
|
||||||
|
|
||||||
|
- [Curl Examples](#curl-examples)
|
||||||
|
- [HTTP API exclusive features](#http-api-exclusive-features)
|
||||||
|
* [RSS/Atom feeds](#rssatom-feeds)
|
||||||
|
* [Images](#images)
|
||||||
|
+ [Create (request)](#create-request)
|
||||||
|
+ [Create (response)](#create-response)
|
||||||
|
+ [Delete](#delete)
|
||||||
|
|
||||||
|
<!-- tocstop -->
|
||||||
|
|
||||||
|
## Curl Examples
|
||||||
|
|
||||||
|
**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}`
|
|
@ -1,2 +0,0 @@
|
||||||
# WebSocket API
|
|
||||||
[Lemmy WebSocket API 2.0 documentation](https://join-lemmy.org/api/index.html)
|
|
Loading…
Reference in a new issue