Add API documentation to docs

2019-07-10 13:20:57 +02:00 · 2019-07-10 13:20:57 +02:00 · 2b508f80e9
commit 2b508f80e9
parent 641532daec
1 changed files with 254 additions and 1 deletions
--- a/docs/3-api-documentation.md
+++ b/docs/3-api-documentation.md
@ -4,4 +4,257 @@ title: API documentation
 permalink: /api
 ---

-# TODO
+# 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/<id>/switches`), sometimes includes the full Member model (eg. `GET /s/<id>/fronters`).
+
+## Endpoints
+
+### `GET /s/<id>`
+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/<id>/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/<id>/switches[?before=<timestamp>]`
+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/<id>/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/<id>`
+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/<id>`
+**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