Skip to content

Commit 2b49c8a

Browse files
neo-jgrecneo-jgrec
committed
docs(api): add a api documenation with their dto
1 parent 1c3eacd commit 2b49c8a

File tree

7 files changed

+713
-0
lines changed

7 files changed

+713
-0
lines changed

‎docs/api/_category_.json

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "Documentation API",
3+
"position": 3,
4+
"link": {
5+
"type": "generated-index",
6+
"description": "API Reference, coarsely generated from source code comments (swagger doc).\n Note that if you want a more reliable and detailed API reference, you should refer to the documentation generated on /api on the running instance of the application."
7+
}
8+
}

‎docs/api/auth.md

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
---
2+
title: Authentication
3+
sidebar_position: 1
4+
---
5+
6+
The authentication is a crucial part of the application. It allows you to identify the user and to restrict access to some parts of the application.
7+
8+
There is several concepts to understand before diving into the authentication system:
9+
- **access token**: A token that is used to authenticate the user. It is sent in the `Authorization` header of the request.
10+
- **refresh token**: A token that is used to get a new access token when the current one is expired. It is sent in the `Authorization` header of the request.
11+
12+
:::note
13+
All the endpoints answer the same body on success (200).
14+
The body is the following:
15+
```js
16+
{
17+
"accessToken": {
18+
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiIxMjM0NTY3ODkwIiwiaWF0IjoxNTE2MjM5MDIyfQ",
19+
"tokenExpiresAt": "2021-01-01T00:00:00.000Z"
20+
},
21+
"refreshToken": {
22+
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiIxMjM0NTY3ODkwIiwiaWF0IjoxNTE2MjM5MDIyfQ",
23+
"tokenExpiresAt": "2021-01-01T00:00:00.000Z"
24+
}
25+
}
26+
```
27+
:::
28+
29+
## Endpoints
30+
31+
In the following, you will find the list of the endpoints that are related to the authentication.
32+
33+
### Register : `POST /auth/register`
34+
35+
This endpoint allows you to register a new user.
36+
37+
:::note
38+
At the moment, the registration is open to everyone. Furthermore, there is no restriction like email or manual validation.
39+
However, thoses features are planned for the future.
40+
:::
41+
42+
#### Parameters
43+
44+
Takes no parameters.
45+
46+
#### Body
47+
48+
- `username` : The username of the user (string), \*(required)
49+
- `email` : The email of the user (string), \*(required)
50+
- `password` : The password of the user (string), \*(required)
51+
52+
:::warning
53+
- The password must be at least 8 characters long and contain at least one uppercase letter, one lowercase letter, one number, and one special character.
54+
- The username must be unique and can only contain those characters : a-z, A-Z, 0-9, -, ., _, @.
55+
- The email (as the username) must be unique and must be a valid email (e.g. `[email protected]`).
56+
:::
57+
58+
**Body example :**
59+
60+
```js
61+
{
62+
"username": "johndoe",
63+
"email": "[email protected]",
64+
"password": "Password1234?"
65+
}
66+
```
67+
68+
---
69+
70+
### Login : `POST /auth/login`
71+
72+
This endpoint allows you to login a user.
73+
74+
#### Parameters
75+
76+
Takes no parameters.
77+
78+
#### Body
79+
80+
The user can connect with either his username or his email.
81+
82+
- `username` : The username or the email of the user (string), \*(semi-required)
83+
- `email` : The email of the user (string), \*(semi-required)
84+
- `password` : The password of the user (string), \*(required)
85+
86+
**Body examples :**
87+
88+
```js
89+
{
90+
"username": "johndoe",
91+
"password": "Password1234?"
92+
}
93+
```
94+
95+
```js
96+
{
97+
"email": "[email protected]",
98+
"password": "Password1234?"
99+
}
100+
```
101+
102+
```js
103+
{
104+
"username": "johndoe",
105+
"email": "[email protected]",
106+
"password": "Password1234?"
107+
}
108+
```
109+
---
110+
111+
### Refresh token : `POST /auth/refresh`
112+
113+
This endpoint allows you to get a new access token when the current one is expired.
114+
115+
#### Parameters
116+
117+
Takes no parameters.
118+
119+
#### Body
120+
121+
- `refreshToken` : The refresh token (string), \*(required)
122+
123+
**Body example :**
124+
125+
```js
126+
{
127+
"refreshToken": "super_token_of_the_turfu"
128+
}
129+
```

‎docs/api/channel.md

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
---
2+
title: Channel
3+
sidebar_position: 3
4+
---
5+
6+
Channels can have several fields, including:
7+
```mermaid
8+
erDiagram
9+
Channel {
10+
String id PK
11+
String name
12+
String type
13+
String topic
14+
Boolean nsfw
15+
Bytes messages
16+
Integer bitrate
17+
Integer userLimit
18+
Integer rateLimitPerUser
19+
Bytes recipients
20+
DateTime createdAt
21+
DateTime updatedAt
22+
String lastMessageId
23+
String serverId
24+
String description
25+
Integer position
26+
Bytes permissionOverwrites
27+
String ownerId
28+
}
29+
```
30+
31+
:::note
32+
There are also other fields (one-to-many, many-to-many relationships) not listed here.
33+
To see the full schema, you can check the [database schema](/development/database).
34+
:::
35+
36+
## Endpoints
37+
38+
Below is the list of endpoints related to channels.
39+
40+
:::warning
41+
All channel-related endpoints are protected by the authentication middleware.
42+
You must provide a valid token in the `Bearer` header to access them.
43+
See the [authentication](/api/authentication) page for more information.
44+
:::
45+
46+
---
47+
48+
### Get channel: `GET /api/channels/:id`
49+
50+
This endpoint allows you to get a channel by its id.
51+
52+
#### Parameters
53+
54+
- `id`: The id of the channel (string), *(required)*
55+
56+
#### Body
57+
58+
Takes no body.
59+
60+
#### Response
61+
62+
- `200`: The channel object (see the [channel dto](/development/dto/channel) for more information)
63+
64+
65+
(*needs login*)
66+
67+
---
68+
69+
### Get all channels: `GET /api/channels`
70+
71+
This endpoint allows you to get all channels.
72+
73+
:::warning
74+
This endpoint is only available for the admin.
75+
:::
76+
77+
#### Parameters
78+
79+
Takes no parameters.
80+
81+
#### Response
82+
83+
- `200`: An array of channel objects (see the [channel dto](/development/dto/channel) for more information)
84+
85+
86+
(*needs login* and *admin privileges*)
87+
88+
---
89+
90+
### Update channel: `PATCH /api/channels/:id`
91+
92+
This endpoint allows you to update a channel by its id.
93+
94+
#### Parameters
95+
96+
- `id`: The id of the channel (string), *(required)*
97+
98+
#### Body
99+
100+
It takes in its body the fields that you want to update (any fields from the [channel dto](/development/dto/channel)).
101+
For instance, if you want to update the name, you can send the following body:
102+
```json
103+
{
104+
"name": "newName"
105+
}
106+
```
107+
108+
#### Response
109+
110+
- `200`: A string that says "Channel updated successfully" *(or something similar)*
111+
112+
113+
(*needs login*)
114+
115+
---
116+
117+
### Delete channel: `DELETE /api/channels/:id`
118+
119+
This endpoint allows you to delete a channel by its id.
120+
121+
#### Parameters
122+
123+
- `id`: The id of the channel (string), *(required)*
124+
125+
#### Body
126+
127+
Takes no body.
128+
129+
#### Response
130+
131+
- `200`: A string that says "Channel deleted successfully" *(or something similar)*
132+
133+
134+
(*needs login*)
135+
136+
---
137+
138+
### Create channel: `POST /api/channels`
139+
140+
This endpoint allows you to create a new channel.
141+
142+
#### Parameters
143+
144+
Takes no parameters.
145+
146+
#### Body
147+
148+
It takes in its body the fields required to create a channel (any fields from the [channel dto](/development/dto/channel)).
149+
For instance, to create a new channel, you can send the following body:
150+
```json
151+
{
152+
"name": "general",
153+
"type": "DM",
154+
"topic": "This is a general channel",
155+
"nsfw": false,
156+
"bitrate": 64000,
157+
"userLimit": 10,
158+
"rateLimitPerUser": 10,
159+
"recipients": [],
160+
"serverId": "37963246-7e9d-4239-a95f-96704c6dcbaa",
161+
"description": "This is a general channel"
162+
}
163+
```
164+
165+
#### Response
166+
167+
- `201`: A string that says "Channel created successfully" *(or something similar)*
168+
169+
170+
(*needs login*)
171+
172+
---
173+
174+
### Add recipients to channel: `POST /api/channels/:id/recipients`
175+
176+
This endpoint allows you to add recipients to a channel by its id.
177+
178+
#### Parameters
179+
180+
- `id`: The id of the channel (string), *(required)*
181+
182+
#### Body
183+
184+
It takes in its body the recipients to add (array of recipient ids).
185+
186+
#### Response
187+
188+
- `200`: A string that says "Recipients added successfully" *(or something similar)*
189+
190+
191+
(*needs login*)
192+
193+
---
194+
195+
### Remove recipients from channel: `DELETE /api/channels/:id/recipients`
196+
197+
This endpoint allows you to remove recipients from a channel by its id.
198+
199+
#### Parameters
200+
201+
- `id`: The id of the channel (string), *(required)*
202+
203+
#### Body
204+
205+
It takes in its body the recipients to remove (array of recipient ids).
206+
207+
#### Response
208+
209+
- `200`: A string that says "Recipients removed successfully" *(or something similar)*
210+
211+
212+
(*needs login*)

0 commit comments

Comments
 (0)