Skip to content

Commit cb7864a

Browse files
JustYuutoJustYuuto
committed
feat: add API documentation for cards and users endpoints
1 parent c7c8689 commit cb7864a

File tree

6 files changed

+297
-3
lines changed

6 files changed

+297
-3
lines changed

‎docs/endpoints/_category_.json

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "Endpoints",
3+
"position": 4,
4+
"link": {
5+
"type": "generated-index",
6+
"title": "Endpoints"
7+
}
8+
}

‎docs/endpoints/cards.md

+84
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
title: Cards
3+
sidebar_position: 2
4+
---
5+
6+
This page contains information about the `/cards` endpoint, which is used to manage your cards.
7+
8+
## Get a card
9+
10+
Get a card by its ID.
11+
12+
### Request
13+
14+
`:id` is the ID of the card you want to get.
15+
16+
```http request
17+
GET /api/cards/:id
18+
```
19+
20+
### Example Response
21+
22+
```json
23+
{
24+
"id": "d1d882ad-b78b-4164-81e3-b1feafe59460",
25+
"type": "server",
26+
"value": "https://discord.gg/miwa"
27+
}
28+
```
29+
30+
:::caution
31+
32+
For types `discord` and `server`, the `value` field will be `null`.
33+
34+
:::
35+
36+
## Create a card
37+
38+
Create a new card.
39+
40+
### Request
41+
42+
```http request
43+
POST /api/cards
44+
Content-Type: application/json
45+
```
46+
47+
Example body:
48+
```json
49+
{
50+
"type": "server",
51+
"value": "https://discord.gg/miwa"
52+
}
53+
```
54+
55+
### Example Response
56+
57+
Returns a 201 status on success, and the card object in the response body.
58+
59+
```json
60+
{
61+
"id": "d1d882ad-b78b-4164-81e3-b1feafe59460",
62+
"type": "server",
63+
"value": "https://discord.gg/miwa"
64+
}
65+
```
66+
67+
## Delete a card
68+
69+
Delete a card by its ID.
70+
71+
### Request
72+
73+
`:id` is the ID of the card you want to delete. Obviously, you can only delete your own cards.
74+
75+
```http request
76+
DELETE /api/cards/:id
77+
```
78+
79+
### Example Response
80+
81+
Returns:
82+
* a 204 status on success.
83+
* a 404 status if the card does not exist.
84+
* a 403 status if the card does not belong to you.

‎docs/endpoints/users.md

+193
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
title: Users
3+
sidebar_position: 1
4+
---
5+
6+
This page contains information about the `/users` endpoint.
7+
8+
## Get a user
9+
10+
Get a user by their username.
11+
12+
### Request
13+
14+
`:username` is the username of the user you want to get. It can be a username or an alias.
15+
16+
```http request
17+
GET /api/user/:username
18+
```
19+
20+
### Example Response
21+
22+
```json
23+
{
24+
"id": "28b841e9-1d54-4142-9b15-5050d620c0ea",
25+
"username": "yuuto",
26+
"display_name": "Yuuto",
27+
"alias": "$",
28+
"bio": "🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸",
29+
"discord_id": "269415459735076864",
30+
"created_at": 1000,
31+
"is_premium": true,
32+
"volume_control": true,
33+
"page_enter_text": null,
34+
"layout": "modern",
35+
"assets": {
36+
"avatar": "https://cdn.miwa.lol/avatars/40380b72-5045-45b2-aa5f-9b806209e762.jpg",
37+
"cursor": null,
38+
"background": "https://cdn.miwa.lol/backgrounds/e893dbf5-3e6b-4246-9118-e33afa17948c.webp",
39+
"audios": [
40+
"https://cdn.miwa.lol/audios/a12593fe-b6dd-4731-ae38-1ebf304a00db.mp3",
41+
"https://cdn.miwa.lol/audios/084214bd-c213-4578-857e-ad935fb924cc.mp3",
42+
"https://cdn.miwa.lol/audios/cdc68c1d-34e2-4d0a-a842-59e02a20dbbc.mp3"
43+
],
44+
"use_discord_avatar": false,
45+
"shuffle_audios": true,
46+
"play_all_audios": true
47+
},
48+
"profile": {
49+
"opacity": 20,
50+
"blur": 9,
51+
"font": "Fira Mono"
52+
},
53+
"colors": {
54+
"accent": "#bd10e0",
55+
"text": "#ffffff",
56+
"background": "#000000",
57+
"badge": "#fff",
58+
"link": "#ffffff",
59+
"monochrome_links": true
60+
},
61+
"effects": {
62+
"background": "snowflakes",
63+
"cursor": "fairy-dust",
64+
"username": "rainbow"
65+
},
66+
"tab": {
67+
"animated_title": "reverse",
68+
"use_avatar": true
69+
},
70+
"privacy": {
71+
"hide_views": false,
72+
"hide_badges": false,
73+
"hide_join_date": false,
74+
"hide_likes": false,
75+
"search_engines_indexing": true
76+
},
77+
"typewriter": {
78+
"enabled": true,
79+
"texts": [
80+
"dev & owner @ miwa.lol",
81+
"discord.gg/miwa"
82+
]
83+
}
84+
}
85+
```
86+
87+
## Get your user
88+
89+
Get the user that is currently authenticated.
90+
91+
### Request
92+
93+
```http request
94+
GET /api/user
95+
```
96+
97+
### Example Response
98+
99+
This is practically the same as the response from the previous endpoint, but with some differences.
100+
101+
```json
102+
{
103+
"id": "28b841e9-1d54-4142-9b15-5050d620c0ea",
104+
"username": "yuuto",
105+
"display_name": "Yuuto",
106+
"alias": "$",
107+
"email": "your@email.com",
108+
"custom_domain": null,
109+
"bio": "🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸🇬🇸",
110+
"discord_id": "269415459735076864",
111+
"created_at": 1000,
112+
"is_premium": true,
113+
"otp_enabled": true,
114+
"volume_control": true,
115+
"page_enter_text": "hi click pls",
116+
"locale": "fr",
117+
"layout": "modern",
118+
"assets": {
119+
"avatar": "https://cdn.miwa.lol/avatars/40380b72-5045-45b2-aa5f-9b806209e762.jpg",
120+
"cursor": null,
121+
"background": "https://cdn.miwa.lol/backgrounds/e893dbf5-3e6b-4246-9118-e33afa17948c.webp",
122+
"audios": [
123+
"https://cdn.miwa.lol/audios/a12593fe-b6dd-4731-ae38-1ebf304a00db.mp3",
124+
"https://cdn.miwa.lol/audios/084214bd-c213-4578-857e-ad935fb924cc.mp3",
125+
"https://cdn.miwa.lol/audios/cdc68c1d-34e2-4d0a-a842-59e02a20dbbc.mp3"
126+
],
127+
"use_discord_avatar": false,
128+
"shuffle_audios": true,
129+
"play_all_audios": true
130+
},
131+
"profile": {
132+
"opacity": 20,
133+
"blur": 9,
134+
"font": "Fira Mono"
135+
},
136+
"colors": {
137+
"accent": "#bd10e0",
138+
"text": "#ffffff",
139+
"background": "#000000",
140+
"badge": "#fff",
141+
"link": "#ffffff",
142+
"monochrome_links": true
143+
},
144+
"effects": {
145+
"background": "snowflakes",
146+
"cursor": "fairy-dust",
147+
"username": "rainbow"
148+
},
149+
"tab": {
150+
"animated_title": "reverse",
151+
"use_avatar": true
152+
},
153+
"privacy": {
154+
"hide_views": false,
155+
"hide_badges": false,
156+
"hide_join_date": false,
157+
"search_engines_indexing": true
158+
},
159+
"typewriter": {
160+
"enabled": true,
161+
"texts": [
162+
"dev & owner @ miwa.lol",
163+
"discord.gg/miwa"
164+
]
165+
}
166+
}
167+
```
168+
169+
## Update your profile
170+
171+
Allows you to update your profile, including your username, display name, alias, bio, and more.
172+
173+
### Request
174+
175+
```http request
176+
PATCH /api/user
177+
```
178+
179+
### Example Request
180+
181+
For example, to update your accent color:
182+
183+
```json
184+
{
185+
"colors": {
186+
"accent": "#bd10e0"
187+
}
188+
}
189+
```
190+
191+
### Response
192+
193+
Returns the updated user object.

‎docs/index.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1-
# Welcome!
1+
---
2+
title: Welcome
3+
sidebar_position: 1
4+
---
25

36
This is the documentation for the [Miwa.lol](https://miwa.lol) API. Please be aware that this is a work in progress and may not be fully accurate.

‎docs/oauth2/index.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
# OAuth2 Apps
1+
---
2+
title: OAuth2 Apps
3+
sidebar_position: 3
4+
---
25

36
OAuth2 apps are used to authenticate with the API. They are used to generate access tokens which are used to authenticate requests to the API.
47

‎docs/using/index.md ‎docs/using.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
# Using the API
1+
---
2+
title: Using the API
3+
sidebar_position: 2
4+
---
25

36
Our API uses OAuth2 for authentication and authorization. This means that you need to obtain an access token to access the API. The access token is used to authenticate your requests to the API and to limit the access of the token to specific resources and actions. See the [OAuth2](/oauth2) documentation for more information on how to obtain an access token.
47

0 commit comments

Comments
 (0)