From 837d78f15fb6ed1b32b61a520134b1b0b4b4e89c Mon Sep 17 00:00:00 2001
From: Lukas Schulte Pelkum <kbrt@protonmail.com>
Date: Thu, 22 Jul 2021 21:00:19 +0200
Subject: [PATCH] Document API

---
 API.md                    | 165 +++++++++++++++++++++++++++++++++++++-
 internal/report/report.go |   2 +-
 internal/web/web.go       |   2 +-
 3 files changed, 166 insertions(+), 3 deletions(-)

diff --git a/API.md b/API.md
index b4ed657..f0e7247 100644
--- a/API.md
+++ b/API.md
@@ -1,3 +1,166 @@
 # API
 
-> This document will contain the documentation for the pasty REST API.
\ No newline at end of file
+The REST API provided by pasty is the most important entrypoint when it comes to interacting with it. Basically everything, including the pasty frontend, is built on top of it.
+To make things easier for other developers who decide to develop something in connection to pasty, everything important about it is documented here.
+
+## Authentication/Authorization
+
+Not everyone should be able to view, edit or delete all pastes. However, admins should be.
+In order to achieve that, an effective auth flow is required.
+
+There are two ways of authenticating:
+
+### 1.) Paste-pecific
+
+The `Authorization` header is set to `Bearer <modification_token>`, where `<modification_token>` is replaced with the corresponding paste-specific **modification token**.
+This authentication is only valid for the requested paste.
+
+### 2.) Admin tokens
+
+The `Authorization` header is set to `Bearer <admin_token>`, where `<admin_token>` is replaced with the configured **administration token**.
+This authentication is valid for all endpoints, regardless of the requested paste.
+
+### Notation
+
+In the folllowing, all endpoints that require an **admin token** are annotated with `[ADMIN]`.
+All endpoints that are accessible through the **admin and modification token** are annotated with `[PASTE_SPECIFIC]`.
+All endpoints that are accessible to everyone are annotated with `[UNSECURED]`.
+
+## Endpoints
+
+### [UNSECURED] Retrieve application information
+
+```http
+GET /api/v2/info
+```
+
+**Request:**
+none
+
+**Response:**
+```json
+{
+    "modificationTokens": true,
+    "reports": true,
+    "version": "dev"
+}
+```
+
+---
+
+### [UNSECURED] Retrieve a paste
+
+```http
+GET /api/v2/pastes/{paste_id}
+```
+
+**Request:**
+none
+
+**Response:**
+```json
+{
+    "id": "paste_id",
+    "content": "paste_content",
+    "created": 0000000000,
+    "autoDelete": false,
+    "metadata": {},
+}
+```
+
+---
+
+### [UNSECURED] Create a paste
+
+```http
+POST /api/v2/pastes
+```
+
+**Request:**
+```js
+{
+    "content": "paste_content", // Required
+    "metadata": {}              // Optional
+}
+```
+
+**Response:**
+```json
+{
+    "id": "paste_id",
+    "content": "paste_content",
+    "created": 0000000000,
+    "autoDelete": false,
+    "metadata": {},
+}
+```
+
+---
+
+### [PASTE_SPECIFIC] Update a paste
+
+```http
+PATCH /api/v2/pastes/{paste_id}
+```
+
+**Request:**
+```js
+{
+    "content": "new_paste_content", // Optional
+    "metadata": {}                  // Optional
+}
+```
+
+**Response:**
+```json
+{
+    "id": "paste_id",
+    "content": "new_paste_content",
+    "created": 0000000000,
+    "autoDelete": false,
+    "metadata": {},
+}
+```
+
+**Notes:**
+* Changes in the `metadata` field only affect the corresponding field and don't override the whole key-value store (`{"metadata": {"foo": "bar"}}` will effectively add or replace the `foo` key but won't affect other keys).
+* To remove a key from the key-value store simply set it to `null`.
+
+---
+
+### [PASTE_SPECIFIC] Delete a paste
+
+```http
+DELETE /api/v2/pastes/{paste_id}
+```
+
+**Request:**
+none
+
+**Response:**
+none
+
+---
+
+### [UNSECURED] Report a paste
+
+```http
+POST /api/v2/pastes/{paste_id}/report
+```
+
+**Request:**
+```json
+{
+    "reason": "reason"
+}
+```
+
+**Response:**
+```js
+{
+    "message": "message"    // An optional message to display to the reporting user
+}
+```
+
+**Notes:**
+* The endpoint is only available if the report system is enabled. Otherwise it will return a `404 Not Found` error.
\ No newline at end of file
diff --git a/internal/report/report.go b/internal/report/report.go
index 320ade1..6f11528 100644
--- a/internal/report/report.go
+++ b/internal/report/report.go
@@ -17,7 +17,7 @@ type ReportRequest struct {
 
 // ReportResponse represents a report response received from the report webhook
 type ReportResponse struct {
-	Message string
+	Message string `json:"message"`
 }
 
 // SendReport sends a report request to the report webhook
diff --git a/internal/web/web.go b/internal/web/web.go
index d8d3d93..3c509b0 100644
--- a/internal/web/web.go
+++ b/internal/web/web.go
@@ -75,7 +75,7 @@ func Serve() error {
 				jsonData, _ := json.Marshal(map[string]interface{}{
 					"version":            static.Version,
 					"modificationTokens": config.Current.ModificationTokens,
-					"reports":            config.Current.Reports,
+					"reports":            config.Current.Reports.Reports,
 				})
 				ctx.SetBody(jsonData)
 			})