mirror of
https://github.com/LemmyNet/joinlemmy-site.git
synced 2024-11-21 20:01:16 +00:00
Making changes to reflect requested lemmy-docs changes
This commit is contained in:
Gary Conroy
parent
cbe7fc18c6
commit
6ab288526b
1 changed files with 35 additions and 49 deletions
|
|
@ -10,60 +10,44 @@ info:
|
|||
[**Lemmy**](https://github.com/LemmyNet/lemmy) is a decentralized alternative to proprietary link aggregators such as Reddit.
|
||||
#### More information...
|
||||
- [Install your own server](https://join.lemmy.ml/docs/en/administration/administration.html)
|
||||
- [Lemmy data types](https://join.lemmy.ml/docs/en/contributing/websocket_http_api.html#data-types)
|
||||
- [Images](https://join.lemmy.ml/docs/en/contributing/websocket_http_api.html#images)
|
||||
- [RSS/Atom feeds](https://join.lemmy.ml/docs/en/contributing/websocket_http_api.html#rss--atom-feeds)
|
||||
- [Rate limiting](https://join.lemmy.ml/docs/en/contributing/websocket_http_api.html#default-rate-limits)
|
||||
- [API reference](link_here)
|
||||
### How to use this WebSocket API document
|
||||
You can either use it to:
|
||||
- **Interactively browse the WebSocket API.** Browse the *Channels*, check out the responses and examples (tailor the *PUBLISH* requests to suit with your favorite WebSocket client - such as [websocat](https://github.com/vi/websocat)).
|
||||
- **Interactively browse the WebSocket API.** Browse the *Channels*, check out the responses and examples (tailor the *PUBLISH* requests to suit with your favorite WebSocket client).
|
||||
For testing purposes, either [set up your own server](https://join.lemmy.ml/docs/en/administration/administration.html) or use the Enterprise server (*ws://enterprise.lemmy.ml/api/v2/ws*)
|
||||
- **[Open and save](asyncapi.yaml) this specification file** and use it with the various [AsyncAPI tools](https://www.asyncapi.com/docs/community/tooling) (perhaps to generate code or documentation).
|
||||
#### Structure of this document
|
||||
|
||||
Connect to <code>ws://***host***/api/v2/ws</code> to get started. If the server supports secure connections, you can use `wss://**server**/api/v1/ws`.
|
||||
#### Testing with websocat
|
||||
|
||||
For example a simple test using [websocat](https://github.com/vi/websocat) might be:
|
||||
|
||||
`websocat ws://127.0.0.1:8536/api/v2/ws -nt`
|
||||
|
||||
A simple test command:
|
||||
|
||||
`{"op": "ListCategories", "data": {}}`
|
||||
|
||||
#### Testing with the [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: {}
|
||||
}));
|
||||
};
|
||||
```
|
||||
|
||||
### Structure of this document
|
||||
- **Channels** - Documents the requests (marked with the PUBLISH button) and responses (marked with SUBSCRIBE) for each endpoint (*channel*)
|
||||
- **Servers** - Lists some publicly-accessible test servers
|
||||
- **Messages** - A summary of the requests and responses (a duplication of the information in **=Channels*)
|
||||
- **Messages** - A summary of the requests and responses (a duplication of the information in **Channels**)
|
||||
- **Schemas** - An alphabetical list of the most commonly accessed data structures in the API.
|
||||
### The HTTP API
|
||||
Lemmy also has an HTTP API which is almost identical to the WebSocket API:
|
||||
- WebSocket API needs `let send = { op: userOperation[op], data: form}` as shown below
|
||||
- HTTP API requires the form (data) at the top level and an HTTP operation (GET, PUT or POST) and endpoint.
|
||||
For example: `POST {username_or_email: X, password: X}`. Endpoints are at `http(s)://host/api/v2/endpoint`. *All request and response strings are in [JSON format](https://www.json.org/json-en.html).*
|
||||
|
||||
|
||||
For more information, see the [http.ts](https://github.com/LemmyNet/lemmy-js-client/blob/main/src/http.ts) file.
|
||||
#### Example (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` |
|
||||
|
||||
#### Examples (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
|
||||
```
|
||||
Lemmy also has an [HTTP API](link_here) which is almost identical to the WebSocket API; however, this WebSocket API is the primary source since it also details the specifics of HTTP API calls.
|
||||
|
||||
license:
|
||||
name: AGPL
|
||||
|
|
@ -1750,9 +1734,7 @@ components:
|
|||
- password
|
||||
properties:
|
||||
username_or_email:
|
||||
type: string
|
||||
description: 'Username or registered email'
|
||||
example: 'lemmy'
|
||||
$ref: '#/components/schemas/username_or_email'
|
||||
password:
|
||||
$ref: '#/components/schemas/password'
|
||||
loginResponse:
|
||||
|
|
@ -5665,6 +5647,10 @@ components:
|
|||
$ref: '#/components/schemas/counts'
|
||||
user:
|
||||
$ref: '#/components/schemas/user'
|
||||
'username_or_email':
|
||||
type: string
|
||||
description: 'Username or registered email'
|
||||
example: 'lemmy'
|
||||
'users_active_day':
|
||||
desciption: Number of 'active' users in the previous 24 hours
|
||||
type: number
|
||||
|
|
|
|||
Loading…
Reference in a new issue