From 2b508f80e95f6d082fd18c3d3defcf1c5053f4d2 Mon Sep 17 00:00:00 2001 From: Ske Date: Wed, 10 Jul 2019 13:20:57 +0200 Subject: [PATCH] Add API documentation to docs --- docs/3-api-documentation.md | 255 +++++++++++++++++++++++++++++++++++- 1 file changed, 254 insertions(+), 1 deletion(-) diff --git a/docs/3-api-documentation.md b/docs/3-api-documentation.md index fcee93bc..350ee408 100644 --- a/docs/3-api-documentation.md +++ b/docs/3-api-documentation.md @@ -4,4 +4,257 @@ title: API documentation permalink: /api --- -# TODO \ No newline at end of file +# API documentation +PluralKit has a basic HTTP REST API for querying and modifying your system. +The root endpoint of the API is `https://api.pluralkit.me/v1/`. + +Endpoints will always return all fields, using `null` when a value is missing. On `PATCH` endpoints, you *must* include +all fields, too. Missing fields will be interpreted as `null`, and `null` fields will have their value removed. To +preserve a value, pass the existing value again. + +## Authentication +Authentication is done with a simple "system token". You can get your system token by running `pk;token` using the +Discord bot, either in a channel with the bot or in DMs. Then, pass this token in the `Authorization` HTTP header +on requests that require it. Failure to do so on endpoints that require authentication will return a `401 Unauthorized`. + +## Models +The following three models (usually represented in JSON format) represent the various objects in PluralKit's API. A `?` after the column type indicates an optional (nullable) parameter. +### System model +|Key|Type|Patchable?|Notes| +|---|---|---|---| +|id|string|No| +|name|string?|Yes|100-character limit. +|description|string?|Yes|1000-character limit. +|tag|string?|Yes| +|avatar_url|url?|Yes|Not validated server-side. +|tz|string?|Yes|Tzdb identifier. Patching with `null` will store `"UTC"`. +|created|datetime|No| + +### Member model +|Key|Type|Patchable?|Notes| +|---|---|---|---| +|id|string|No| +|name|string?|Yes|50-character limit. +|description|string?|Yes|1000-character limit. +|color|color?|Yes|6-char hex (eg. `ff7000`), sans `#`. +|avatar_url|url?|Yes|Not validated server-side. +|birthday|date?|Yes|ISO-8601 (`YYYY-MM-DD`) format, year of `0001` means hidden year. +|prefix|string?|Yes|| +|suffix|string?|Yes|| +|created|datetime|No| +### Switch model +|Key|Type|Notes| +|---|---|---| +|timestamp|datetime| +|members|list of id/Member|Is sometimes in plain ID list form (eg. `GET /s//switches`), sometimes includes the full Member model (eg. `GET /s//fronters`). + +## Endpoints + +### `GET /s/` +Queries a system by its 5-character ID, and returns information about it. If the system doesn't exist, returns `404 Not Found`. + +#### Example request + GET https://api.pluralkit.me/v1/s/abcde + +#### Example response +```json +{ + "id": "abcde", + "name": "My System", + "description": "This is my system description. Yay.", + "tag": "[MySys]", + "avatar_url": "https://path/to/avatar/image.png", + "tz": "Europe/Copenhagen", + "created": "2019-01-01T14:30:00.987654Z" +} +``` + +### `GET /s//members` +Queries a system's member list by its 5-character ID. If the system doesn't exist, returns `404 Not Found`. + +#### Example request + GET https://api.pluralkit.me/v1/s/abcde/members + +#### Example response +```json +[ + { + "id": "qwert", + "name": "Craig Johnson", + "color": "ff7000", + "avatar_url": "https://path/to/avatar/image.png", + "birthday": "1997-07-14", + "pronouns": "he/him or they/them", + "description": "I am Craig, example user extraordinaire.", + "prefix": "[", + "suffix": "]", + "created": "2019-01-01T15:00:00.654321Z" + } +] +``` + +### `GET /s//switches[?before=]` +Returns a system's switch history in newest-first chronological order, with a maximum of 100 switches. If the system doesn't exist, returns `404 Not Found`. +Optionally takes a `?before=` query parameter with an ISO-8601-formatted timestamp, and will only return switches +that happen before that timestamp. + +#### Example request + GET https://api.pluralkit.me/v1/s/abcde/switches?before=2019-03-01T14:00:00Z + +#### Example response +```json +[ + { + "timestamp": "2019-02-23T14:20:59.123456Z", + "members": ["qwert", "yuiop"] + }, + { + "timestamp": "2019-02-22T12:00:00Z", + "members": ["yuiop"] + }, + { + "timestamp": "2019-02-20T09:30:00Z", + "members": [] + } +] +``` + +### `GET /s//fronters` +Returns a system's current fronter(s), with fully hydrated member objects. If the system doesn't exist, *or* the system has no registered switches, returns `404 Not Found`. + +#### Example request + GET https://api.pluralkit.me/v1/s/abcde/fronters + +#### Example response +```json +{ + "timestamp": "2019-07-09T17:22:46.47441Z", + "members": [ + { + "id": "qwert", + "name": "Craig Johnson", + "color": "ff7000", + "avatar_url": "https://path/to/avatar/image.png", + "birthday": "1997-07-14", + "pronouns": "he/him or they/them", + "description": "I am Craig, example user extraordinaire.", + "prefix": "[", + "suffix": "]", + "created": "2019-01-01T15:00:00.654321Z" + } + ] +} +``` + +### `PATCH /s` +**Requires authentication.** + +Edits your own system's information. Missing fields will be set to `null`. Will return the new system object. + +#### Example request + PATCH https://api.pluralkit.me/v1/s + +```json +{ + "name": "New System Name", + "tag": "{Sys}", + "avatar_url": "https://path/to/new/avatar.png" + "tz": "America/New_York" +} +``` +(note the absence of a `description` field, which is set to null in the response) + +#### Example response +```json +{ + "id": "abcde", + "name": "New System Name", + "description": null, + "tag": "{Sys}", + "avatar_url": "https://path/to/new/avatar.png", + "tz": "America/New_York", + "created": "2019-01-01T14:30:00.987654Z" +} +``` + +### `POST /s/switches` +**Requires authentication.** + +Registers a new switch to your own system given a list of member IDs. + +#### Example request + POST https://api.pluralkit.me/v1/s/switches + +```json +{ + "members": ["qwert", "yuiop"] +} +``` + +#### Example response +(`204 No Content`) + +### `GET /m/` +Queries a member's information by its 5-character member ID. If the member does not exist, will return `404 Not Found`. + +#### Example request + GET https://api.pluralkit.me/v1/m/qwert + +#### Example response +```json +{ + "id": "qwert", + "name": "Craig Johnson", + "color": "ff7000", + "avatar_url": "https://path/to/avatar/image.png", + "birthday": "1997-07-14", + "pronouns": "he/him or they/them", + "description": "I am Craig, example user extraordinaire.", + "prefix": "[", + "suffix": "]", + "created": "2019-01-01T15:00:00.654321Z" +} +``` + +### `PATCH /m/` +**Requires authentication.** + +Edits a member's information. Missing fields will be set to `null`. Will return the new member object. Member must (obviously) belong to your own system. + +#### Example request + PATCH https://api.pluralkit.me/v1/m/qwert + +```json +{ + "name": "Craig Peterson", + "color": null, + "avatar_url": "https://path/to/new/image.png", + "birthday": "1997-07-14", + "pronouns": "they/them", + "description": "I am Craig, cooler example user extraordinaire.", + "prefix": "[" +} +``` +(note the absence of a `suffix` field, which is set to null in the response) + +#### Example response +```json +{ + "id": "qwert", + "name": "Craig Peterson", + "color": null, + "avatar_url": "https://path/to/new/image.png", + "birthday": "1997-07-14", + "pronouns": "they/them", + "description": "I am Craig, cooler example user extraordinaire.", + "prefix": "[", + "suffix": null, + "created": "2019-01-01T15:00:00.654321Z" +} +``` + +## Version history +* 2019-07-10 **(v1)** + * First specified version +* (prehistory) + * Initial release \ No newline at end of file