feat(api): ✨ Add Roles API

docs/api/index.md

@@ -6,14 +6,18 @@ Some more information about the Mastodon API can be found in the [Mastodon API d
 
 ## Emoji API
 
-For administrators. Please read [the documentation](./emojis.md).
+For client developers. Please read [the documentation](./emojis.md).
+
+## Roles API
+
+For client developers. Please read [the documentation](./roles.md).
 
 ## Moderation API
 
 > [!WARNING]
 > **Not implemented.**
 
-For administrators. Please read [the documentation](./moderation.md).
+For client developers. Please read [the documentation](./moderation.md).
 
 ## Frontend API
 

docs/api/roles.md

@@ -0,0 +1,153 @@
+# Roles API
+
+The Roles API lets users manage roles given to them by administrators. This API is available to all users.
+
+> [!WARNING]
+> The API for **administrators** is different (and unimplemented): this is the API for **users**.
+>
+> Furthermore, users can only manage roles if they have the `roles` permission, and the role they wish to manage does not have a higher priority than their highest priority role.
+
+## Priorities
+
+Roles have a priority, which determines the order in which they are applied. Roles with higher priorities take precedence over roles with lower priorities.
+
+Additionally, users cannot remove or add roles with a higher priority than their highest priority role.
+
+## Visibility
+
+Roles can be visible or invisible. Invisible roles are not shown to users in the UI, but they can still be managed via the API.
+
+> [!WARNING]
+> All roles assigned to a user are public information and can be retrieved via the API. The visibility of a role only affects whether it is shown in the UI, which clients can choose to respect or not.
+
+## Permissions
+
+```ts
+// Last updated: 2024-06-07
+// Search for "RolePermissions" in the source code (GitHub search bar) for the most up-to-date version
+enum RolePermissions {
+    MANAGE_NOTES = "notes",
+    MANAGE_OWN_NOTES = "owner:note",
+    MANAGE_ACCOUNTS = "accounts",
+    MANAGE_OWN_ACCOUNT = "owner:account",
+    MANAGE_EMOJIS = "emojis",
+    MANAGE_OWN_EMOJIS = "owner:emoji",
+    MANAGE_MEDIA = "media",
+    MANAGE_OWN_MEDIA = "owner:media",
+    MANAGE_BLOCKS = "blocks",
+    MANAGE_OWN_BLOCKS = "owner:block",
+    MANAGE_FILTERS = "filters",
+    MANAGE_OWN_FILTERS = "owner:filter",
+    MANAGE_MUTES = "mutes",
+    MANAGE_OWN_MUTES = "owner:mute",
+    MANAGE_REPORTS = "reports",
+    MANAGE_OWN_REPORTS = "owner:report",
+    MANAGE_SETTINGS = "settings",
+    MANAGE_OWN_SETTINGS = "owner:settings",
+    MANAGE_ROLES = "roles",
+    IGNORE_RATE_LIMITS = "ignore_rate_limits",
+    IMPERSONATE = "impersonate",
+    MANAGE_INSTANCE = "instance",
+    MANAGE_INSTANCE_FEDERATION = "instance:federation",
+    MANAGE_INSTANCE_SETTINGS = "instance:settings",
+    OAUTH = "oauth",
+}
+```
+
+### Manage Roles
+
+The `roles` permission allows the user to manage roles, including adding and removing roles from themselves. This permission is required to use the Roles API.
+
+### Impersonate
+
+The `impersonate` permission allows the user to impersonate other users (logging in with their credentials). This is a dangerous permission and should be used with caution.
+
+### Manage Instance
+
+The `instance` permission allows the user to manage the instance, including viewing logs, restarting the instance, and more.
+
+### Manage Instance Federation
+
+The `instance:federation` permission allows the user to manage the instance's federation settings, including blocking and unblocking other instances.
+
+### Manage Instance Settings
+
+The `instance:settings` permission allows the user to manage the instance's settings, including changing the instance's name, description, and more.
+
+### OAuth2
+
+The `oauth` permission is required for users to log in to the instance. Users who do not have this permission will not be able to log in.
+
+## Get Roles
+
+```http
+GET /api/v1/roles
+```
+
+Retrieves a list of roles that the user has.
+
+### Response
+
+```ts
+// 200 OK
+{
+    id: string;
+    name: string;
+    permissions: RolePermissions[];
+    priority: number;
+    description: string | null;
+    visible: boolean;
+    icon: string | null
+}[];
+```
+
+## Get Role
+
+```http
+GET /api/v1/roles/:id
+```
+
+Retrieves information about a role.
+
+### Response
+
+```ts
+// 200 OK
+{
+    id: string;
+    name: string;
+    permissions: RolePermissions[];
+    priority: number;
+    description: string | null;
+    visible: boolean;
+    icon: string | null
+}
+```
+
+## Add Role
+
+```http
+POST /api/v1/roles/:id
+```
+
+Adds the role with the given ID to the user making the request.
+
+### Response
+
+```ts
+// 204 No Content
+```
+
+## Remove Role
+
+```http
+DELETE /api/v1/roles/:id
+```
+
+Removes the role with the given ID from the user making the request.
+
+### Response
+
+```ts
+// 204 No Content
+```