+ Badge structure docs

Also this is a new pattern but I'm going to start actually using those anchor tags
to self link to other places in the page.

+ /badge/new endpoint docs
+ /badge/delete endpoint docs
+ /badge/update/name endpoint docs
+ /badge/update/color endpoint docs
+ /badge/update/perms endpoint docs

! Small point but apparantly this layout is somewhat printer friendly
:^) Just thought that was kinda neat.
This commit is contained in:
shockrah 2021-07-01 21:09:26 -07:00
parent 995717afb3
commit a69ad24a45
4 changed files with 153 additions and 1 deletions

View File

@ -0,0 +1,135 @@
---
title: Badges
anchor: badges-ep
weight: 19
---
### `/badge/new`
It should be noted that while alpha values are technically valid it is up to
individual clients to decide what to do with that value. Personally I suggest not
doing anything with the alpha value so that it doesn't matter but that is up to
the client developer.
* Required query string parameters:
* badge\_name: String
* Name to assign to the new badge
* badge\_perms: u64
* Permissions mask which apply to the badge
* Semi optional query string parameter:
* badge\_color: u32
* If not included the color will default to `0xffffffff`
* Required permissions
* NEW\_BADGE
* Returns
* A new [badge](#badges) behind the JSON key `badge`.
### `/badge/delete`
* Required query string parameters:
* id: u64
* ID of the target badge to delete
* Required permissions
* DELETE\_BADGE
* Returns
* HTTP 200 on success
Example:
```
> POST /badge/new
< {
< "badge": {
< "id": 1,
< "name": "badge-name-here",
< "color": 1234,
< "perms": 1234,
< }
< }
```
### `/badge/list`
* No query string required.
* No required permissions, only that the client have a valid JWT.
* Returns
* Array of [Badges](#badges) behind the JSON key `badges`.
Example:
```
> GET /badge/list
< {
< "badges": [
< {
< "id": 1,
< "name": "badge-name-here",
< "color": 1234,
< "perms": 1234,
< },
< ...
< ]
< }
```
### `/badge/update/color`
* Required query string parameters:
* badge\_id: u64
* ID of the target badge to update.
* badge\_color: u32
* The new color to update to
* Required permissions:
* UPDATE\_COLOR\_BADGE
* Returns:
* HTTP 200
### `/badge/update/name`
* Required query string parameters:
* badge\_id: u64
* ID of the target badge toupdate.
* badge\_name: String
* The new badge name to assign.
* Required permissions:
* UPDATE\_NAME\_BADGE
### `/badge/update/perms`
* Required query string parameters:
* badge\_id: u64
* ID of the target badge toupdate.
* badge\_perms: u64
* Represented as a regular integer this is the bitmap of permissions which apply to the badge
* Required permissions:
* UPDATE\_PERMS\_BADGE

View File

@ -0,0 +1,14 @@
---
title: Badges
anchor: badges
weight: 55
---
Name | Type
:--------:|:-------:
`name` | `String`
`id` | `u64`
`color` | `u32`
`perms` | `u64`

View File

@ -13,6 +13,7 @@ Channels are made up of the following components
name | `String`
kind | `i32`
description| `String`
badge\_ids| `Array<u32>`
Channels have two valid types or (more semantically) `kind` values:

View File

@ -14,10 +14,11 @@ Name | Type
secret | `String`
status | `i32`
permissions| `u64`
badge\_ids | `Array<u32>`
### JWT
This data is retrieved after a sucessful `/login` hit.
This data is retrieved after a successful `/login` hit.
Name | Type
:-----:|:------:
@ -31,6 +32,7 @@ This data is retrieved after a sucessful `/login` hit.
name | `String`
status | `i32`
permissions| `u64`
badge\_ids | `Array<u32>`
For users _without_ the `USER_FETCH` permission the only two fields with actual data is `id` and `name`. The other fields will be set to 0.