diff --git a/src/en/SUMMARY.md b/src/en/SUMMARY.md index 3c61f9a..b7a4123 100644 --- a/src/en/SUMMARY.md +++ b/src/en/SUMMARY.md @@ -17,10 +17,9 @@ - [Federation Overview](federation/overview.md) - [Lemmy Protocol](federation/lemmy_protocol.md) - [Client Development](client_development/client_development.md) + - [API docs](/api) + - [HTTP API extras](client_development/http_api_extras.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) - [Contributing](contributing/contributing.md) - [Docker Development](contributing/docker_development.md) diff --git a/src/en/client_development/api_reference.md b/src/en/client_development/api_reference.md deleted file mode 100644 index 8d4afab..0000000 --- a/src/en/client_development/api_reference.md +++ /dev/null @@ -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. - - - -- [Basic usage](#basic-usage) -- [Data types](#data-types) - * [Lemmy types](#lemmy-types) - * [Lower-level types](#lower-level-types) -- [Default rate limits](#default-rate-limits) - - - -## 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). diff --git a/src/en/client_development/client_development.md b/src/en/client_development/client_development.md index a6d67ba..99b780a 100644 --- a/src/en/client_development/client_development.md +++ b/src/en/client_development/client_development.md @@ -1,6 +1,5 @@ # Client Development +- [API docs](/api) +- [HTTP API extras](client_development/http_api_extras) - [Theming Guide](client_development/theming.md) -- [API reference](client_development/api_reference.md) -- [WebSocket API](https://join-lemmy.org/api/index.html) -- [HTTP API](client_development/http_api.md) \ No newline at end of file diff --git a/src/en/client_development/http_api.md b/src/en/client_development/http_api.md index c522c0b..301012c 100644 --- a/src/en/client_development/http_api.md +++ b/src/en/client_development/http_api.md @@ -1,116 +1 @@ -# Lemmy HTTP API - - - - -- [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) - - - -## 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 { - 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). +# HTTP API diff --git a/src/en/client_development/http_api_extras.md b/src/en/client_development/http_api_extras.md new file mode 100644 index 0000000..de07c97 --- /dev/null +++ b/src/en/client_development/http_api_extras.md @@ -0,0 +1,80 @@ +# Lemmy HTTP API Extras + + + +- [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) + + + +## 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}` diff --git a/src/en/client_development/websocket_api.md b/src/en/client_development/websocket_api.md deleted file mode 100644 index b97237a..0000000 --- a/src/en/client_development/websocket_api.md +++ /dev/null @@ -1,2 +0,0 @@ -# WebSocket API -[Lemmy WebSocket API 2.0 documentation](https://join-lemmy.org/api/index.html)