Document API

API.md

@@ -1,3 +1,166 @@
 # API
 
-> This document will contain the documentation for the pasty REST API.
+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.

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

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)
 			})