From 795ea5dfc2549b50265cea2f7b7a774356a735b4 Mon Sep 17 00:00:00 2001
From: Maxim Filippov <colixer@gmail.com>
Date: Fri, 4 Oct 2019 18:58:44 +0300
Subject: [PATCH] Move HTTP verb to the header (admin_api.md)

---
 docs/api/admin_api.md | 190 +++++++++++++++++++++++++++++---------------------
 1 file changed, 109 insertions(+), 81 deletions(-)

diff --git a/docs/api/admin_api.md b/docs/api/admin_api.md
index ee9e68cb1..045686bf4 100644
--- a/docs/api/admin_api.md
+++ b/docs/api/admin_api.md
@@ -2,11 +2,10 @@
 
 Authentication is required and the user must be an admin.
 
-## `/api/pleroma/admin/users`
+## `GET /api/pleroma/admin/users`
 
 ### List users
 
-- Method `GET`
 - Query Params:
   - *optional* `query`: **string** search term (e.g. nickname, domain, nickname@domain)
   - *optional* `filters`: **string** comma-separated string of filters:
@@ -47,11 +46,10 @@ Authentication is required and the user must be an admin.
 }
 ```
 
-## `/api/pleroma/admin/users`
+## `DELETE /api/pleroma/admin/users`
 
 ### Remove a user
 
-- Method `DELETE`
 - Params:
   - `nickname`
 - Response: User’s nickname
@@ -69,31 +67,30 @@ Authentication is required and the user must be an admin.
   ]
 - Response: User’s nickname
 
-## `/api/pleroma/admin/users/follow`
+## `POST /api/pleroma/admin/users/follow`
+
 ### Make a user follow another user
 
-- Methods: `POST`
 - Params:
- - `follower`: The nickname of the follower
- - `followed`: The nickname of the followed
+  - `follower`: The nickname of the follower
+  - `followed`: The nickname of the followed
 - Response:
- - "ok"
+  - "ok"
+
+## `POST /api/pleroma/admin/users/unfollow`
 
-## `/api/pleroma/admin/users/unfollow`
 ### Make a user unfollow another user
 
-- Methods: `POST`
 - Params:
- - `follower`: The nickname of the follower
- - `followed`: The nickname of the followed
+  - `follower`: The nickname of the follower
+  - `followed`: The nickname of the followed
 - Response:
- - "ok"
+  - "ok"
 
-## `/api/pleroma/admin/users/:nickname/toggle_activation`
+## `PATCH /api/pleroma/admin/users/:nickname/toggle_activation`
 
 ### Toggle user activation
 
-- Method: `PATCH`
 - Params:
   - `nickname`
 - Response: User’s object
@@ -106,27 +103,26 @@ Authentication is required and the user must be an admin.
 }
 ```
 
-## `/api/pleroma/admin/users/tag`
+## `PUT /api/pleroma/admin/users/tag`
 
 ### Tag a list of users
 
-- Method: `PUT`
 - Params:
   - `nicknames` (array)
   - `tags` (array)
 
+## `DELETE /api/pleroma/admin/users/tag`
+
 ### Untag a list of users
 
-- Method: `DELETE`
 - Params:
   - `nicknames` (array)
   - `tags` (array)
 
-## `/api/pleroma/admin/users/:nickname/permission_group`
+## `GET /api/pleroma/admin/users/:nickname/permission_group`
 
 ### Get user user permission groups membership
 
-- Method: `GET`
 - Params: none
 - Response:
 
@@ -137,13 +133,12 @@ Authentication is required and the user must be an admin.
 }
 ```
 
-## `/api/pleroma/admin/users/:nickname/permission_group/:permission_group`
+## `GET /api/pleroma/admin/users/:nickname/permission_group/:permission_group`
 
 Note: Available `:permission_group` is currently moderator and admin. 404 is returned when the permission group doesn’t exist.
 
 ### Get user user permission groups membership per permission group
 
-- Method: `GET`
 - Params: none
 - Response:
 
@@ -154,48 +149,47 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
 }
 ```
 
+## `POST /api/pleroma/admin/users/:nickname/permission_group/:permission_group`
+
 ### Add user in permission group
 
-- Method: `POST`
 - Params: none
 - Response:
   - On failure: `{"error": "…"}`
   - On success: JSON of the `user.info`
 
+## `DELETE /api/pleroma/admin/users/:nickname/permission_group/:permission_group`
+
 ### Remove user from permission group
 
-- Method: `DELETE`
 - Params: none
 - Response:
   - On failure: `{"error": "…"}`
   - On success: JSON of the `user.info`
 - Note: An admin cannot revoke their own admin status.
 
-## `/api/pleroma/admin/users/:nickname/activation_status`
+## `PUT /api/pleroma/admin/users/:nickname/activation_status`
 
 ### Active or deactivate a user
 
-- Method: `PUT`
 - Params:
   - `nickname`
   - `status` BOOLEAN field, false value means deactivation.
 
-## `/api/pleroma/admin/users/:nickname_or_id`
+## `GET /api/pleroma/admin/users/:nickname_or_id`
 
 ### Retrive the details of a user
 
-- Method: `GET`
 - Params:
   - `nickname` or `id`
 - Response:
   - On failure: `Not found`
   - On success: JSON of the user
 
-## `/api/pleroma/admin/users/:nickname_or_id/statuses`
+## `GET /api/pleroma/admin/users/:nickname_or_id/statuses`
 
 ### Retrive user's latest statuses
 
-- Method: `GET`
 - Params:
   - `nickname` or `id`
   - *optional* `page_size`: number of statuses to return (default is `20`)
@@ -204,29 +198,28 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
   - On failure: `Not found`
   - On success: JSON array of user's latest statuses
 
-## `/api/pleroma/admin/relay`
+## `POST /api/pleroma/admin/relay`
 
 ### Follow a Relay
 
-- Methods: `POST`
 - Params:
   - `relay_url`
 - Response:
   - On success: URL of the followed relay
 
+## `DELETE /api/pleroma/admin/relay`
+
 ### Unfollow a Relay
 
-- Methods: `DELETE`
 - Params:
   - `relay_url`
 - Response:
   - On success: URL of the unfollowed relay
 
-## `/api/pleroma/admin/users/invite_token`
+## `POST /api/pleroma/admin/users/invite_token`
 
 ### Create an account registration invite token
 
-- Methods: `POST`
 - Params:
   - *optional* `max_use` (integer)
   - *optional* `expires_at` (date string e.g. "2019-04-07")
@@ -244,11 +237,10 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
 }
 ```
 
-## `/api/pleroma/admin/users/invites`
+## `GET /api/pleroma/admin/users/invites`
 
 ### Get a list of generated invites
 
-- Methods: `GET`
 - Params: none
 - Response:
 
@@ -270,11 +262,10 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
 }
 ```
 
-## `/api/pleroma/admin/users/revoke_invite`
+## `POST /api/pleroma/admin/users/revoke_invite`
 
 ### Revoke invite by token
 
-- Methods: `POST`
 - Params:
   - `token`
 - Response:
@@ -292,21 +283,18 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
 }
 ```
 
-
-## `/api/pleroma/admin/users/email_invite`
+## `POST /api/pleroma/admin/users/email_invite`
 
 ### Sends registration invite via email
 
-- Methods: `POST`
 - Params:
   - `email`
   - `name`, optional
 
-## `/api/pleroma/admin/users/:nickname/password_reset`
+## `GET /api/pleroma/admin/users/:nickname/password_reset`
 
 ### Get a password reset token for a given nickname
 
-- Methods: `GET`
 - Params: none
 - Response:
 
@@ -317,18 +305,17 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
 }
 ```
 
-
-## `/api/pleroma/admin/users/:nickname/force_password_reset`
+## `PATCH /api/pleroma/admin/users/:nickname/force_password_reset`
 
 ### Force passord reset for a user with a given nickname
 
-- Methods: `PATCH`
 - Params: none
 - Response: none (code `204`)
 
-## `/api/pleroma/admin/reports`
+## `GET /api/pleroma/admin/reports`
+
 ### Get a list of reports
-- Method `GET`
+
 - Params:
   - *optional* `state`: **string** the state of reports. Valid values are `open`, `closed` and `resolved`
   - *optional* `limit`: **integer** the number of records to retrieve
@@ -343,7 +330,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
 
 ```json
 {
-  "total" : 1,
+  "totalReports" : 1,
   "reports": [
     {
       "account": {
@@ -481,13 +468,24 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
         }
       ]
     }
+  ],
+  "totalGroupedReports": 1,
+  "groupedReports": [
+    {
+      "date": "2019-01-01", // date of the latest report
+      "account": { ... }, // author of the reported status
+      "status": { ... }, // reported status
+      "actors": [{ ... }, { ... }], // accounts that sent reports on the status
+      "reports": [{ ... }]
+    }
   ]
 }
 ```
 
-## `/api/pleroma/admin/reports/:id`
+## `GET /api/pleroma/admin/reports/:id`
+
 ### Get an individual report
-- Method `GET`
+
 - Params:
   - `id`
 - Response:
@@ -496,22 +494,41 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
     - 404 Not Found `"Not found"`
   - On success: JSON, Report object (see above)
 
-## `/api/pleroma/admin/reports/:id`
-### Change the state of the report
-- Method `PUT`
+## `PATCH /api/pleroma/admin/reports`
+
+### Change the state of one or multiple reports
+
 - Params:
-  - `id`
-  - `state`: required, the new state. Valid values are `open`, `closed` and `resolved`
+
+```json
+  `reports`: [
+    {
+      `id`, // required, report id
+      `state` // required, the new state. Valid values are `open`, `closed` and `resolved`
+    },
+    ...
+  ]
+```
+
 - Response:
   - On failure:
-    - 400 Bad Request `"Unsupported state"`
-    - 403 Forbidden `{"error": "error_msg"}`
-    - 404 Not Found `"Not found"`
-  - On success: JSON, Report object (see above)
+    - 400 Bad Request, JSON:
+
+    ```json
+      [
+        {
+          `id`, // report id
+          `error` // error message
+        }
+      ]
+    ```
+
+  - On success: `204`, empty response
+
+## `POST /api/pleroma/admin/reports/:id/respond`
 
-## `/api/pleroma/admin/reports/:id/respond`
 ### Respond to a report
-- Method `POST`
+
 - Params:
   - `id`
   - `status`: required, the message
@@ -581,9 +598,10 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
 }
 ```
 
-## `/api/pleroma/admin/statuses/:id`
+## `PUT /api/pleroma/admin/statuses/:id`
+
 ### Change the scope of an individual reported status
-- Method `PUT`
+
 - Params:
   - `id`
   - `sensitive`: optional, valid values are `true` or `false`
@@ -595,9 +613,10 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
     - 404 Not Found `"Not found"`
   - On success: JSON, Mastodon Status entity
 
-## `/api/pleroma/admin/statuses/:id`
+## `DELETE /api/pleroma/admin/statuses/:id`
+
 ### Delete an individual reported status
-- Method `DELETE`
+
 - Params:
   - `id`
 - Response:
@@ -606,11 +625,12 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
     - 404 Not Found `"Not found"`
   - On success: 200 OK `{}`
 
+## `GET /api/pleroma/admin/config/migrate_to_db`
 
-## `/api/pleroma/admin/config/migrate_to_db`
 ### Run mix task pleroma.config migrate_to_db
+
 Copy settings on key `:pleroma` to DB.
-- Method `GET`
+
 - Params: none
 - Response:
 
@@ -618,9 +638,12 @@ Copy settings on key `:pleroma` to DB.
 {}
 ```
 
-## `/api/pleroma/admin/config/migrate_from_db`
+## `GET /api/pleroma/admin/config/migrate_from_db`
+
 ### Run mix task pleroma.config migrate_from_db
+
 Copy all settings from DB to `config/prod.exported_from_db.secret.exs` with deletion from DB.
+
 - Method `GET`
 - Params: none
 - Response:
@@ -629,10 +652,12 @@ Copy all settings from DB to `config/prod.exported_from_db.secret.exs` with dele
 {}
 ```
 
-## `/api/pleroma/admin/config`
+## `GET /api/pleroma/admin/config`
+
 ### List config settings
+
 List config settings only works with `:pleroma => :instance => :dynamic_configuration` setting to `true`.
-- Method `GET`
+
 - Params: none
 - Response:
 
@@ -648,8 +673,10 @@ List config settings only works with `:pleroma => :instance => :dynamic_configur
 }
 ```
 
-## `/api/pleroma/admin/config`
+## `POST /api/pleroma/admin/config`
+
 ### Update config settings
+
 Updating config settings only works with `:pleroma => :instance => :dynamic_configuration` setting to `true`.
 Module name can be passed as string, which starts with `Pleroma`, e.g. `"Pleroma.Upload"`.
 Atom keys and values can be passed with `:` in the beginning, e.g. `":upload"`.
@@ -672,7 +699,6 @@ Compile time settings (need instance reboot):
   - `Pleroma.Upload` -> `:proxy_remote`
   - `:instance` -> `:upload_limit`
 
-- Method `POST`
 - Params:
   - `configs` => [
     - `group` (string)
@@ -727,9 +753,10 @@ Compile time settings (need instance reboot):
 }
 ```
 
-## `/api/pleroma/admin/moderation_log`
+## `GET /api/pleroma/admin/moderation_log`
+
 ### Get moderation log
-- Method `GET`
+
 - Params:
   - *optional* `page`: **integer** page number
   - *optional* `page_size`: **integer** number of log entries per page (default is `50`)
@@ -756,8 +783,9 @@ Compile time settings (need instance reboot):
 ```
 
 ## `POST /api/pleroma/admin/reload_emoji`
+
 ### Reload the instance's custom emoji
-* Method `POST`
-* Authentication: required
-* Params: None
-* Response: JSON, "ok" and 200 status
+
+- Authentication: required
+- Params: None
+- Response: JSON, "ok" and 200 status