# 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.