Peninsula/docs/api-v1.md

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

Replies

Mark own Account for Deletion

{
	"accounts": {
		"<uuid>": {
			"delete-at": "<unix-timestamp>"
		}
	}
}

Mark other Accounts for Deletion

{
	"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.
• 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.

Replies

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.