Merge pull request 'Document Akkoma API' (#678) from Oneric/akkoma:doc-akkomapi into develop

Reviewed-on: AkkomaGang/akkoma#678

CHANGELOG.md

@@ -9,6 +9,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ## Added
 - Full compatibility with Erlang OTP26
 - handling of GET /api/v1/preferences
+- Akkoma API is now documented
 
 ## Changed
 - OTP builds are now built on erlang OTP26

docs/docs/administration/monitoring.md

@@ -3,7 +3,7 @@
 If you run akkoma, you may be inclined to collect metrics to ensure your instance is running smoothly,
 and that there's nothing quietly failing in the background.
 
-To facilitate this, akkoma exposes prometheus metrics to be scraped.
+To facilitate this, akkoma exposes a dashboard and prometheus metrics to be scraped.
 
 ## Prometheus
 
@@ -31,3 +31,15 @@ Once you have your token of the form `Bearer $ACCESS_TOKEN`, you can use that in
   - targets:
     - example.com
 ```
+
+## Dashboard
+
+Administrators can access a live dashboard under `/phoenix/live_dashboard`
+giving an overview of uptime, software versions, database stats and more.
+
+The dashboard also includes a variation of the prometheus metrics, however
+they do not exactly match due to respective limitations of the dashboard
+and the prometheus exporter.
+Even more important, the dashboard collects metrics locally in the browser
+only while the page is open and cannot give a view on their past history.
+For proper monitoring it is recommended to set up prometheus.

docs/docs/development/API/akkoma_api.md

@@ -0,0 +1,146 @@
+# Akkoma API
+
+Request authentication (if required) and parameters work the same as for [Pleroma API](pleroma_api.md).
+
+## `/api/v1/akkoma/preferred_frontend/available`
+### Returns the available frontends which can be picked as the preferred choice
+* Method: `GET`
+* Authentication: not required
+* Params: none
+* Response: JSON
+* Example response:
+```json
+["pleroma-fe/stable"]
+```
+
+!!! note
+    There’s also a browser UI under `/akkoma/frontend`
+    for interactively querying and changing this.
+
+## `/api/v1/akkoma/preferred_frontend`
+### Configures the preferred frontend of this session
+* Method: `PUT`
+* Authentication: not required
+* Params:
+    * `frontend_name`: STRING containing one of the available frontends
+* Response: JSON
+* Example response:
+```json
+{"frontend_name":"pleroma-fe/stable"}
+```
+
+!!! note
+    There’s also a browser UI under `/akkoma/frontend`
+    for interactively querying and changing this.
+
+## `/api/v1/akkoma/metrics`
+### Provides metrics for Prometheus to scrape
+* Method: `GET`
+* Authentication: required (admin:metrics)
+* Params: none
+* Response: text
+* Example response:
+```
+# HELP pleroma_remote_users_total
+# TYPE pleroma_remote_users_total gauge
+pleroma_remote_users_total 25
+# HELP pleroma_local_statuses_total
+# TYPE pleroma_local_statuses_total gauge
+pleroma_local_statuses_total 17
+# HELP pleroma_domains_total
+# TYPE pleroma_domains_total gauge
+pleroma_domains_total 4
+# HELP pleroma_local_users_total
+# TYPE pleroma_local_users_total gauge
+pleroma_local_users_total 3
+...
+```
+
+## `/api/v1/akkoma/translation/languages`
+### Returns available source and target languages for automated text translation
+* Method: `GET`
+* Authentication: required
+* Params: none
+* Response: JSON
+* Example response:
+```json
+{
+  "source": [
+    {"code":"LV", "name":"Latvian"},
+    {"code":"ZH", "name":"Chinese (traditional)"},
+    {"code":"EN-US", "name":"English (American)"}
+  ],
+  "target": [
+    {"code":"EN-GB", "name":"English (British)"},
+    {"code":"JP", "name":"Japanese"}
+  ]
+}
+```
+
+## `/api/v1/akkoma/frontend_settings/:frontend_name`
+### Lists all configuration profiles of the selected frontend for the current user
+* Method: `GET`
+* Authentication: required
+* Params: none
+* Response: JSON
+* Example response:
+```json
+[
+  {"name":"default","version":31}
+]
+```
+
+## `/api/v1/akkoma/frontend_settings/:frontend_name/:profile_name`
+### Returns the full selected frontend settings profile of the current user
+* Method: `GET`
+* Authentication: required
+* Params: none
+* Response: JSON
+* Example response:
+```json
+{
+  "version": 31,
+  "settings": {
+    "streaming": true,
+    "conversationDisplay": "tree",
+    ...
+  }
+}
+```
+
+## `/api/v1/akkoma/frontend_settings/:frontend_name/:profile_name`
+### Updates the frontend settings profile
+* Method: `PUT`
+* Authentication: required
+* Params:
+    * `version`: INTEGER
+    * `settings`: JSON object containing the entire new settings
+* Response: JSON
+* Example response:
+```json
+{
+  "streaming": false,
+  "conversationDisplay": "tree",
+  ...
+}
+```
+
+!!! note
+    The `version` field must be increased by exactly one on each update
+
+## `/api/v1/akkoma/frontend_settings/:frontend_name/:profile_name`
+### Drops the specified frontend settings profile
+* Method: `DELETE`
+* Authentication: required
+* Params: none
+* Response: JSON
+* Example response:
+```json
+{"deleted":"ok"}
+```
+
+
+## `/api/v1/timelines/bubble`
+### Returns a timeline for the local and closely related instances
+Works like all other Mastodon-API timeline queries with the documented
+[Akkoma-specific additions and tweaks](./differences_in_mastoapi_responses.md#timelines).

docs/docs/development/API/differences_in_mastoapi_responses.md

@@ -1,6 +1,6 @@
 # Differences in Mastodon API responses from vanilla Mastodon
 
-A Akkoma instance can be identified by "<Mastodon version> (compatible; Pleroma <version>)" present in `version` field in response from `/api/v1/instance`
+A Akkoma instance can be identified by "<Mastodon version> (compatible; Akkoma <version>)" present in `version` field in response from `/api/v1/instance`
 
 ## Flake IDs
 
@@ -8,20 +8,28 @@ Akkoma uses 128-bit ids as opposed to Mastodon's 64 bits. However, just like Mas
 
 ## Timelines
 
+In addition to Mastodon’s timelines, there is also a “bubble timeline” showing
+posts from the local instance and a set of closely related instances as chosen
+by the administrator. It is available under `/api/v1/timelines/bubble`.
+
 Adding the parameter `with_muted=true` to the timeline queries will also return activities by muted (not by blocked!) users.
 
 Adding the parameter `exclude_visibilities` to the timeline queries will exclude the statuses with the given visibilities. The parameter accepts an array of visibility types (`public`, `unlisted`, `private`, `direct`), e.g., `exclude_visibilities[]=direct&exclude_visibilities[]=private`.
 
-Adding the parameter `reply_visibility` to the public and home timelines queries will filter replies. Possible values: without parameter (default) shows all replies, `following` - replies directed to you or users you follow, `self` - replies directed to you.
+Adding the parameter `reply_visibility` to the public, bubble or home timelines queries will filter replies. Possible values: without parameter (default) shows all replies, `following` - replies directed to you or users you follow, `self` - replies directed to you.
 
 Adding the parameter `instance=lain.com` to the public timeline will show only statuses originating from `lain.com` (or any remote instance).
 
-Home, public, hashtag & list timelines accept these parameters:
+All but the direct timeline accept these parameters:
 
 - `only_media`: show only statuses with media attached
-- `local`: show only local statuses
 - `remote`: show only remote statuses
 
+Home, public, hashtag & list timelines further accept:
+
+- `local`: show only local statuses
+
+
 ## Statuses
 
 - `visibility`: has additional possible values `list` and `local` (for local-only statuses)

lib/pleroma/web/api_spec/operations/instance_operation.ex

@@ -137,7 +137,7 @@ defmodule Pleroma.Web.ApiSpec.InstanceOperation do
         "background_upload_limit" => 4_000_000,
         "background_image" => "/static/image.png",
         "banner_upload_limit" => 4_000_000,
-        "description" => "Pleroma: An efficient and flexible fediverse server",
+        "description" => "Akkoma: The cooler fediverse server",
         "email" => "lain@lain.com",
         "languages" => ["en"],
         "max_toot_chars" => 5000,
@@ -160,7 +160,7 @@ defmodule Pleroma.Web.ApiSpec.InstanceOperation do
         "urls" => %{
           "streaming_api" => "wss://lain.com"
         },
-        "version" => "2.7.2 (compatible; Pleroma 2.0.50-536-g25eec6d7-develop)"
+        "version" => "2.7.2 (compatible; Akkoma 3.9.3-232-g6fde75e1-develop)"
       }
     }
   end