more accurate api docs to meet with what is currently supported
This commit is contained in:
shockrah
parent
25fb3f5bb2
commit
5b63f0113b
165
docs/api.md
165
docs/api.md
@ -2,113 +2,150 @@
|
||||
|
||||
Voice connections are not yet authored as they are far from being implemented
|
||||
|
||||
## Auth Routes
|
||||
What's documented here? Any endpoint that is implemented to some degree. If something here is implemented but not yet tested it will still be listed here but just marked with **UNTESTED**.
|
||||
|
||||
### Logging in
|
||||
**NOTE**: Unless otherwise stated endpoints take their parameters via a JSON body. Even if it's a GET request freechat uses HTTP bodies like mad. At some point this might change however it's primarily because it makes more semantic sense to query data using a GET in some cases.
|
||||
|
||||
Authenticated routes require a session key which this route provides, given a previously invited user's credentials
|
||||
|
||||
## Authentication
|
||||
|
||||
Required for basically every endpoint is:
|
||||
|
||||
1. `id` - the server assigned user id
|
||||
|
||||
2. `secret` - the server assigned
|
||||
|
||||
**A word on permissions**: while you should have the permissions assigned to you cached somewhere server does a check for your permissions on the instance anyway so there's no need to supply this to the server.
|
||||
|
||||
### Obtaining ad id + secret
|
||||
|
||||
For instance owners you can use the command-line option `-c` or `--create-owner` to create an account with owner level permissions. It does without saying(except here) that this should only be used for the _most important people to the instance_ **the owners**.
|
||||
|
||||
## Invites
|
||||
|
||||
```
|
||||
/auth/login
|
||||
{
|
||||
id: i64,
|
||||
expires: bool,
|
||||
uses: i32 | null
|
||||
}
|
||||
```
|
||||
|
||||
Parameters:
|
||||
* id
|
||||
### Fields
|
||||
|
||||
User id provided by the instance
|
||||
- id : timestamp which doubles as the invite's expire date
|
||||
|
||||
* secret
|
||||
- expires : Boolean value which tells us whether or not to ignore the id(timestamp) expire value.
|
||||
|
||||
API key provided by the instance
|
||||
- uses : Either `i32` or `null`. Counts how many times the invite can be used. Null means we ignore this field: by default this field should be set to null, as invites expire due to their age first.
|
||||
|
||||
Return:
|
||||
* api-key
|
||||
### Invites Endpoints
|
||||
|
||||
Binary string base64 encoded. This encoding is not to be undone or further authentication _will_ fail.
|
||||
* expiration
|
||||
* `GET /invites/create`
|
||||
|
||||
Unix time stamp dictating when this key should be deleted server side. Though the server may delete the key later than this time-stamp the client can request a new token via `/auth/login` or `/auth/refresh`.
|
||||
|
||||
Basic users can create invites which expire and optionally have a use limit. More privileged users can create invites that do not expire. Both types of users can create invites which have no use limit.
|
||||
|
||||
### Leaving an instance
|
||||
* `GET /invite/<code>`
|
||||
|
||||
Parameters
|
||||
* id
|
||||
User id provided by the instance
|
||||
* secret
|
||||
API key provided by the instance
|
||||
Allows a user that isn't part of the server to join. Updates the invite data accordingly assuming everything is valid.
|
||||
|
||||
Return:
|
||||
* On success: A simple HTTP 200 response; empty body.
|
||||
On success it responds to the client with the following user structure.
|
||||
|
||||
* On failure: An HTTP 400 Bad Request response; which parameter is wrong is not specified to avoid enumeration style attacks.
|
||||
```
|
||||
{
|
||||
id: u64,
|
||||
name: String,
|
||||
secret: String,
|
||||
joindate: i64,
|
||||
status: i32,
|
||||
permissions: u64
|
||||
}
|
||||
```
|
||||
|
||||
The status fields have the following acceptable values:
|
||||
|
||||
* Online := 0
|
||||
|
||||
* Offline:= 1
|
||||
|
||||
* Away := 2
|
||||
|
||||
* Do Not Disturb := 3
|
||||
|
||||
__Secret__: Base64 encoded string, as its generated by a cryptographically random byte string 64 bytes long. All characters are URL safe. The string itself is hashed and salted into the database and checked on each attempted use.
|
||||
|
||||
## Channels
|
||||
|
||||
```
|
||||
/channels/list/voice
|
||||
/channels/list/text
|
||||
{
|
||||
id: u64,
|
||||
name: String,
|
||||
description: String | null,
|
||||
kind: i32
|
||||
}
|
||||
```
|
||||
|
||||
Return:
|
||||
List of struct::Channels owned by the server voice/text
|
||||
### Fields
|
||||
|
||||
/channels/voice/<channel>
|
||||
* id : ...
|
||||
|
||||
* name : ...
|
||||
|
||||
* description : can be either null or some string
|
||||
|
||||
* kind : `Voice Channels := 1` and `Text Channels := 2`
|
||||
|
||||
### Channel Endpoints
|
||||
|
||||
|
||||
* `GET /channels/list`
|
||||
|
||||
Returns: Full list of channels in no particular order
|
||||
|
||||
Return:
|
||||
List of struct::Members in that given channel
|
||||
|
||||
## Messaging
|
||||
|
||||
```
|
||||
/message/recent/<channel>
|
||||
```
|
||||
**UNTESTED + UNIMPLEMENTED**: route is a work in progress
|
||||
|
||||
Parameters:
|
||||
* from::UnixTimestamp<u64>
|
||||
* `GET /message/recent`
|
||||
|
||||
DateTime from which to pull messages. Max value on this route can be no more than 72 hours in the past. To pull further messages you will need to use the `/message/range` route.
|
||||
**Requires Parameter**: from<i64>
|
||||
|
||||
|
||||
```
|
||||
/message/range
|
||||
```
|
||||
Pull up to the last 72 hours of messages, most clients should aim for less however, especially for servers that are more active as this request could end up taking forever or simply returns way too much data.
|
||||
|
||||
Parameters:
|
||||
* start::UnixTimestamp<u64>
|
||||
|
||||
* end::UnixTimestamp<u64>
|
||||
**UNTESTED + UNIMPLEMENTED**: route is a work in progress
|
||||
|
||||
On this route instances by default allow up to 1 week worth of range. Note of course that the closer a client gets to this maximum the longer it will take to load. Some instances may be configured to only return a certain number of messages as well so it is worthwhile to check the bounds of the messages a client receives.
|
||||
* `GET /message/range`
|
||||
|
||||
On success:
|
||||
A json encoded list of `struct::Message` will be returned with a 200 Ok
|
||||
**Requires Parameter**: from<i64>
|
||||
|
||||
On paramter failure:
|
||||
HTTP 400 Bad request
|
||||
**Requires Parameter**: to<i64>
|
||||
|
||||
On server error:
|
||||
HTTP 500 Internal Server Error
|
||||
**On success**: A json encoded list of messages sorted by the order they were received by the server
|
||||
|
||||
**On paramter failure**: HTTP 400 Bad request
|
||||
|
||||
**On server error**: HTTP 500 Internal Server Error
|
||||
|
||||
|
||||
## Administrative Instance Routes
|
||||
|
||||
The following routes can only be used by logged in users who have badges with administrative permissions.
|
||||
The following routes can only be used by logged in users who have badges with administrative permissions or greater.
|
||||
|
||||
* `POST /admin/setpermissions`
|
||||
|
||||
**Requires Parameter**: target-id
|
||||
|
||||
**Requires Permissions**: Admin
|
||||
|
||||
Sets the permissions for that user assuming they are not also an admin
|
||||
|
||||
|
||||
```
|
||||
/admin/setperm
|
||||
```
|
||||
* `POST /owner/newadmin`
|
||||
|
||||
Parameter
|
||||
**Requires Parameter**: target-id
|
||||
|
||||
* permission<u64>
|
||||
|
||||
The permission provided is applied internally as a bit mask, a full list of permissions can be found under the permissions sections.
|
||||
|
||||
|
||||
## Permissions
|
||||
|
||||
Below is a list of currently supported permissions which badges can have. Keep in mind the size of these badges is 64 bits long and is stored internally as unsigned 64 bit integers.
|
||||
**Requires Permissions**: Owner
|
||||
|
||||
Gives that user admin level permissions, does nothing with other owners
|
||||
|
||||
Loading…
Reference in New Issue
Block a user