109 lines
3.4 KiB
Markdown
109 lines
3.4 KiB
Markdown
|
# Peninsula API Documentation (v1.0)
|
||
|
|
This document aims to instruct developers on how to implement the Peninsula style Archipelago API. The Peninsula style API is a passive poll based API architecture enabling distributed processing of all requests.
|
||
|
|
|
||
|
|
## API Endpoints
|
||
|
|
These endpoints are all available under the path `/api/1.0/` for compatibility and future proofing.
|
||
|
|
|
||
|
|
### /api/1.0/accounts/
|
||
|
|
Provides endpoints related to client authentication, linking, management and similar.
|
||
|
|
|
||
|
|
#### `GET /api/1.0/accounts/`
|
||
|
|
List all currently registered accounts.
|
||
|
|
|
||
|
|
#### `POST /api/1.0/accounts/register/`
|
||
|
|
Register a new client with the system. This is an [Illegal Request](#Illegal-Request) if the client is already logged in.
|
||
|
|
|
||
|
|
##### Parameters
|
||
|
|
|
||
|
|
|
||
|
|
#### `POST /api/1.0/accounts/login/`
|
||
|
|
Log in as an existing client. This is an [Illegal Request](#Illegal-Request) if the client is already logged in.
|
||
|
|
|
||
|
|
#### `POST /api/1.0/accounts/logout/`
|
||
|
|
Perform the necessary steps to log out. This is an [Unauthorized Request](#Unauthorized-Request) if not already logged in.
|
||
|
|
|
||
|
|
#### `POST /api/1.0/accounts/delete/`
|
||
|
|
Mark one or more accounts for deletion.
|
||
|
|
|
||
|
|
##### Parameters
|
||
|
|
| Type | Name | Description |
|
||
|
|
|---|---|---|
|
||
|
|
| POST Data | accounts[string] | A zero-indexed array of client UUIDs to delete. Optional. |
|
||
|
|
|
||
|
|
##### Behavior
|
||
|
|
- If the client is not logged in this request should be considered an [Unauthorized Request](#Unauthorized-Request).
|
||
|
|
- If the client is logged in and no `accounts` parameter was provided, the accounts account should be marked for deletion.
|
||
|
|
- If the client is logged in and `accounts` parameter was provided, and the client is authorized to perform this, the accounts listed should be marked for deletion.
|
||
|
|
- In all other cases, this should be considered an [Illegal Request](Illegal-Request).
|
||
|
|
|
||
|
|
##### Replies
|
||
|
|
###### Mark own Account for Deletion
|
||
|
|
```http
|
||
|
|
{
|
||
|
|
"accounts": {
|
||
|
|
"<uuid>": {
|
||
|
|
"delete-at": "<unix-timestamp>"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
###### Mark other Accounts for Deletion
|
||
|
|
```http
|
||
|
|
{
|
||
|
|
"accounts": {
|
||
|
|
"<uuid>": {
|
||
|
|
"delete-at": "<unix-timestamp>"
|
||
|
|
},
|
||
|
|
"<uuid>": {
|
||
|
|
"delete-at": "<unix-timestamp>"
|
||
|
|
},
|
||
|
|
"<uuid>": {
|
||
|
|
"delete-at": "<unix-timestamp>"
|
||
|
|
},
|
||
|
|
// ...
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
#### `POST /api/1.0/accounts/restore/`
|
||
|
|
Unmark an account for deletion. Can only be performed by the account itself.
|
||
|
|
|
||
|
|
##### Parameters
|
||
|
|
No Parameters.
|
||
|
|
|
||
|
|
##### Behavior
|
||
|
|
- If the client is not logged in this request should be considered an [Unauthorized Request](#Unauthorized-Request).
|
||
|
|
- If the client is logged in and the account exists, the account should be unmarked for deletion.
|
||
|
|
- In all other cases, this should be considered an [Illegal Request](Illegal-Request).
|
||
|
|
|
||
|
|
##### Replies
|
||
|
|
```http
|
||
|
|
Clear-Cookie: session
|
||
|
|
|
||
|
|
{
|
||
|
|
"session": null
|
||
|
|
"accounts": {
|
||
|
|
"<uuid>": null
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
#### `POST /api/1.0/accounts/expunge/`
|
||
|
|
Forcefully delete an account
|
||
|
|
|
||
|
|
### Rooms
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
## Terminology
|
||
|
|
|
||
|
|
###### Unauthorized Request
|
||
|
|
An unauthorized request is a request for which the client did not provide the necessary authentification to perform the request. The expected response to these is a `401 Unauthorized` status.
|
||
|
|
|
||
|
|
###### Forbidden Request
|
||
|
|
A forbidden request is a request for which authorization was provided, but it does not provide the necessary rights to perform the action. The expected response to these is a `403 Forbidden` state.
|
||
|
|
|
||
|
|
###### Illegal Request
|
||
|
|
An illegal request is a request which is not valid in the current context. The expected response to these is a `400 Bad Request` status.
|