Removing docs which are soon to be replaced by a proper wiki page
This commit is contained in:
shockrah
parent
efb8aa94de
commit
e693d7e62b
151
docs/api.md
151
docs/api.md
@ -1,151 +0,0 @@
|
||||
# API
|
||||
|
||||
Voice connections are not yet authored as they are far from being implemented
|
||||
|
||||
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**.
|
||||
|
||||
**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.
|
||||
|
||||
|
||||
## 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
|
||||
|
||||
```
|
||||
{
|
||||
id: i64,
|
||||
expires: bool,
|
||||
uses: i32 | null
|
||||
}
|
||||
```
|
||||
|
||||
### Fields
|
||||
|
||||
- id : timestamp which doubles as the invite's expire date
|
||||
|
||||
- expires : Boolean value which tells us whether or not to ignore the id(timestamp) expire value.
|
||||
|
||||
- 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.
|
||||
|
||||
### Invites Endpoints
|
||||
|
||||
* `GET /invites/create`
|
||||
|
||||
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.
|
||||
|
||||
* `GET /invite/<code>`
|
||||
|
||||
Allows a user that isn't part of the server to join. Updates the invite data accordingly assuming everything is valid.
|
||||
|
||||
On success it responds to the client with the following user structure.
|
||||
|
||||
```
|
||||
{
|
||||
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
|
||||
|
||||
```
|
||||
{
|
||||
id: u64,
|
||||
name: String,
|
||||
description: String | null,
|
||||
kind: i32
|
||||
}
|
||||
```
|
||||
|
||||
### Fields
|
||||
|
||||
* 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
|
||||
|
||||
|
||||
## Messaging
|
||||
|
||||
**UNTESTED + UNIMPLEMENTED**: route is a work in progress
|
||||
|
||||
* `GET /message/recent`
|
||||
|
||||
**Requires Parameter**: from<i64>
|
||||
|
||||
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.
|
||||
|
||||
|
||||
**UNTESTED + UNIMPLEMENTED**: route is a work in progress
|
||||
|
||||
* `GET /message/range`
|
||||
|
||||
**Requires Parameter**: from<i64>
|
||||
|
||||
**Requires Parameter**: to<i64>
|
||||
|
||||
**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 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
|
||||
|
||||
|
||||
* `POST /owner/newadmin`
|
||||
|
||||
**Requires Parameter**: target-id
|
||||
|
||||
**Requires Permissions**: Owner
|
||||
|
||||
Gives that user admin level permissions, does nothing with other owners
|
||||
@ -1,13 +0,0 @@
|
||||
#!/bin/sh
|
||||
|
||||
# Builds all docs into a single easily searchable document
|
||||
# Builds: HTML PDF TEXT versions of the documents.
|
||||
|
||||
chapters='api.md structures.md'
|
||||
|
||||
for chap in $chapters;do
|
||||
cat $chap
|
||||
done > freechat-docs.md
|
||||
|
||||
pandoc freechat-docs.md -o freechat-docs.pdf
|
||||
pandoc freechat-docs.md -o freechat-docs.html
|
||||
@ -1,50 +0,0 @@
|
||||
# Structures
|
||||
|
||||
Below are various structures that client builds can expect to receive.
|
||||
These are not representative of how instances internally store data but what a client can expect to receive from different API requests.
|
||||
|
||||
1. Member
|
||||
|
||||
```
|
||||
Member {
|
||||
name: string
|
||||
id: u64
|
||||
permissions: u64
|
||||
badges: List<Badge>
|
||||
}
|
||||
```
|
||||
|
||||
2. Channel
|
||||
|
||||
```
|
||||
Channel {
|
||||
name: string
|
||||
description: string
|
||||
type: integer [1=Voice Channel, 2=Text Channel]
|
||||
}
|
||||
```
|
||||
|
||||
3. Message
|
||||
|
||||
While `Message` responses don't specify what channel they belong a channel
|
||||
does have to be used to request these so it's up to the client to store these
|
||||
in a way that makes sense.
|
||||
|
||||
```
|
||||
Message {
|
||||
author: Member
|
||||
date: u64 -> [unix timestamp since epoch]
|
||||
content: string
|
||||
}
|
||||
```
|
||||
|
||||
4. Badge
|
||||
|
||||
```
|
||||
Badge {
|
||||
name: string
|
||||
permissions: u64
|
||||
color: u32
|
||||
}
|
||||
|
||||
```
|
||||
Loading…
Reference in New Issue
Block a user