diff options
Diffstat (limited to 'docs/API')
| -rw-r--r-- | docs/API/admin_api.md | 217 | ||||
| -rw-r--r-- | docs/API/differences_in_mastoapi_responses.md | 14 | ||||
| -rw-r--r-- | docs/API/pleroma_api.md | 73 |
3 files changed, 179 insertions, 125 deletions
diff --git a/docs/API/admin_api.md b/docs/API/admin_api.md index d98a78af0..47acd240e 100644 --- a/docs/API/admin_api.md +++ b/docs/API/admin_api.md @@ -3,7 +3,7 @@ Authentication is required and the user must be an admin. Configuration options: - + * `[:auth, :enforce_oauth_admin_scope_usage]` — OAuth admin scope requirement toggle. If `true`, admin actions explicitly demand admin OAuth scope(s) presence in OAuth token (client app must support admin scopes). If `false` and token doesn't have admin scope(s), `is_admin` user flag grants access to admin-specific actions. @@ -665,27 +665,14 @@ 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` - -### Run mix task pleroma.config migrate_to_db - -Copy settings on key `:pleroma` to DB. - -- Params: none -- Response: - -```json -{} -``` - -## `GET /api/pleroma/admin/config/migrate_from_db` - -### Run mix task pleroma.config migrate_from_db +## `GET /api/pleroma/admin/restart` -Copy all settings from DB to `config/prod.exported_from_db.secret.exs` with deletion from DB. +### Restarts pleroma application - Params: none - Response: + - On failure: + - 400 Bad Request `"To use this endpoint you need to enable configuration from database."` ```json {} @@ -693,67 +680,139 @@ Copy all settings from DB to `config/prod.exported_from_db.secret.exs` with dele ## `GET /api/pleroma/admin/config` -### List config settings +### Get list of merged default settings with saved in database. -List config settings only works with `:pleroma => :instance => :dynamic_configuration` setting to `true`. +*If `need_reboot` flag exists in response, instance must be restarted, so reboot time settings can take effect.* -- Params: none +**Only works when configuration from database is enabled.** + +- Params: + - `only_db`: true (*optional*, get only saved in database settings) - Response: + - On failure: + - 400 Bad Request `"To use this endpoint you need to enable configuration from database."` ```json { - configs: [ + "configs": [ { - "group": string, - "key": string or string with leading `:` for atoms, - "value": string or {} or [] or {"tuple": []} + "group": ":pleroma", + "key": "Pleroma.Upload", + "value": [] } - ] + ], + "need_reboot": true } ``` + need_reboot - *optional*, if were changed reboot time settings. ## `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"`. -Tuples can be passed as `{"tuple": ["first_val", Pleroma.Module, []]}`. -`{"tuple": ["some_string", "Pleroma.Some.Module", []]}` will be converted to `{"some_string", Pleroma.Some.Module, []}`. -Keywords can be passed as lists with 2 child tuples, e.g. -`[{"tuple": ["first_val", Pleroma.Module]}, {"tuple": ["second_val", true]}]`. +*If `need_reboot` flag exists in response, instance must be restarted, so reboot time settings can take effect.* + +**Only works when configuration from database is enabled.** -If value contains list of settings `[subkey: val1, subkey2: val2, subkey3: val3]`, it's possible to remove only subkeys instead of all settings passing `subkeys` parameter. E.g.: -{"group": "pleroma", "key": "some_key", "delete": "true", "subkeys": [":subkey", ":subkey3"]}. +Some modifications are necessary to save the config settings correctly: -Compile time settings (need instance reboot): -- all settings by this keys: +- strings which start with `Pleroma.`, `Phoenix.`, `Tesla.` or strings like `Oban`, `Ueberauth` will be converted to modules; +``` +"Pleroma.Upload" -> Pleroma.Upload +"Oban" -> Oban +``` +- strings starting with `:` will be converted to atoms; +``` +":pleroma" -> :pleroma +``` +- objects with `tuple` key and array value will be converted to tuples; +``` +{"tuple": ["string", "Pleroma.Upload", []]} -> {"string", Pleroma.Upload, []} +``` +- arrays with *tuple objects* will be converted to keywords; +``` +[{"tuple": [":key1", "value"]}, {"tuple": [":key2", "value"]}] -> [key1: "value", key2: "value"] +``` + +Most of the settings will be applied in `runtime`, this means that you don't need to restart the instance. But some settings are applied in `compile time` and require a reboot of the instance, such as: +- all settings inside these keys: - `:hackney_pools` - `:chat` - - `Pleroma.Web.Endpoint` - - `Pleroma.Repo` -- part settings: - - `Pleroma.Captcha` -> `:seconds_valid` - - `Pleroma.Upload` -> `:proxy_remote` - - `:instance` -> `:upload_limit` - -- Params: - - `configs` => [ - - `group` (string) - - `key` (string or string with leading `:` for atoms) - - `value` (string, [], {} or {"tuple": []}) - - `delete` = true (optional, if parameter must be deleted) - - `subkeys` [(string with leading `:` for atoms)] (optional, works only if `delete=true` parameter is passed, otherwise will be ignored) +- partially settings inside these keys: + - `:seconds_valid` in `Pleroma.Captcha` + - `:proxy_remote` in `Pleroma.Upload` + - `:upload_limit` in `:instance` + +- Params: + - `configs` - array of config objects + - config object params: + - `group` - string (**required**) + - `key` - string (**required**) + - `value` - string, [], {} or {"tuple": []} (**required**) + - `delete` - true (*optional*, if setting must be deleted) + - `subkeys` - array of strings (*optional*, only works when `delete=true` parameter is passed, otherwise will be ignored) + +*When a value have several nested settings, you can delete only some nested settings by passing a parameter `subkeys`, without deleting all settings by key.* +``` +[subkey: val1, subkey2: val2, subkey3: val3] \\ initial value +{"group": ":pleroma", "key": "some_key", "delete": true, "subkeys": [":subkey", ":subkey3"]} \\ passing json for deletion +[subkey2: val2] \\ value after deletion +``` + +*Most of the settings can be partially updated through merge old values with new values, except settings value of which is list or is not keyword.* + +Example of setting without keyword in value: +```elixir +config :tesla, :adapter, Tesla.Adapter.Hackney +``` + +List of settings which support only full update by key: +```elixir +@full_key_update [ + {:pleroma, :ecto_repos}, + {:quack, :meta}, + {:mime, :types}, + {:cors_plug, [:max_age, :methods, :expose, :headers]}, + {:auto_linker, :opts}, + {:swarm, :node_blacklist}, + {:logger, :backends} ] +``` -- Request (example): +List of settings which support only full update by subkey: +```elixir +@full_subkey_update [ + {:pleroma, :assets, :mascots}, + {:pleroma, :emoji, :groups}, + {:pleroma, :workers, :retries}, + {:pleroma, :mrf_subchain, :match_actor}, + {:pleroma, :mrf_keyword, :replace} + ] +``` +*Settings without explicit key must be sended in separate config object params.* +```elixir +config :quack, + level: :debug, + meta: [:all], + ... +``` ```json { - configs: [ + "configs": [ + {"group": ":quack", "key": ":level", "value": ":debug"}, + {"group": ":quack", "key": ":meta", "value": [":all"]}, + ... + ] +} +``` +- Request: + +```json +{ + "configs": [ { - "group": "pleroma", + "group": ":pleroma", "key": "Pleroma.Upload", "value": [ {"tuple": [":uploader", "Pleroma.Uploaders.Local"]}, @@ -763,7 +822,7 @@ Compile time settings (need instance reboot): {"tuple": [":proxy_opts", [ {"tuple": [":redirect_on_failure", false]}, {"tuple": [":max_body_length", 1048576]}, - {"tuple": [":http": [ + {"tuple": [":http", [ {"tuple": [":follow_redirect", true]}, {"tuple": [":pool", ":upload"]}, ]]} @@ -779,18 +838,54 @@ Compile time settings (need instance reboot): ``` - Response: - + - On failure: + - 400 Bad Request `"To use this endpoint you need to enable configuration from database."` ```json { - configs: [ + "configs": [ { - "group": string, - "key": string or string with leading `:` for atoms, - "value": string or {} or [] or {"tuple": []} + "group": ":pleroma", + "key": "Pleroma.Upload", + "value": [...] } - ] + ], + "need_reboot": true } ``` +need_reboot - *optional*, if were changed reboot time settings. + +## ` GET /api/pleroma/admin/config/descriptions` + +### Get JSON with config descriptions. +Loads json generated from `config/descriptions.exs`. + +- Params: none +- Response: + +```json +[{ + "group": ":pleroma", // string + "key": "ModuleName", // string + "type": "group", // string or list with possible values, + "description": "Upload general settings", // string + "children": [ + { + "key": ":uploader", // string or module name `Pleroma.Upload` + "type": "module", + "description": "Module which will be used for uploads", + "suggestions": ["module1", "module2"] + }, + { + "key": ":filters", + "type": ["list", "module"], + "description": "List of filter modules for uploads", + "suggestions": [ + "module1", "module2", "module3" + ] + } + ] +}] +``` ## `GET /api/pleroma/admin/moderation_log` diff --git a/docs/API/differences_in_mastoapi_responses.md b/docs/API/differences_in_mastoapi_responses.md index 7f5d7681d..06de90f71 100644 --- a/docs/API/differences_in_mastoapi_responses.md +++ b/docs/API/differences_in_mastoapi_responses.md @@ -29,6 +29,7 @@ Has these additional fields under the `pleroma` object: - `spoiler_text`: a map consisting of alternate representations of the `spoiler_text` property with the key being it's mimetype. Currently the only alternate representation supported is `text/plain` - `expires_at`: a datetime (iso8601) that states when the post will expire (be deleted automatically), or empty if the post won't expire - `thread_muted`: true if the thread the post belongs to is muted +- `emoji_reactions`: A list with emoji / reaction maps. The format is `{name: "☕", count: 1, me: true}`. Contains no information about the reacting users, for that use the `/statuses/:id/reactions` endpoint. ## Attachments @@ -46,7 +47,7 @@ The `id` parameter can also be the `nickname` of the user. This only works in th Has these additional fields under the `pleroma` object: - `tags`: Lists an array of tags for the user -- `relationship{}`: Includes fields as documented for Mastodon API https://docs.joinmastodon.org/api/entities/#relationship +- `relationship{}`: Includes fields as documented for Mastodon API https://docs.joinmastodon.org/entities/relationship/ - `is_moderator`: boolean, nullable, true if user is a moderator - `is_admin`: boolean, nullable, true if user is an admin - `confirmation_pending`: boolean, true if a new user account is waiting on email confirmation to be activated @@ -87,6 +88,9 @@ Behavior has changed: - `/api/v1/accounts/search`: Does not require authentication +## Search (global) + +Unlisted posts are available in search results, they are considered to be public posts that shouldn't be shown in local/federated timeline. ## Notifications @@ -100,6 +104,14 @@ The `type` value is `move`. Has an additional field: - `target`: new account +### EmojiReact Notification + +The `type` value is `pleroma:emoji_reaction`. Has these fields: + +- `emoji`: The used emoji +- `account`: The account of the user who reacted +- `status`: The status that was reacted on + ## GET `/api/v1/notifications` Accepts additional parameters: diff --git a/docs/API/pleroma_api.md b/docs/API/pleroma_api.md index 7228d805b..07e0af5e5 100644 --- a/docs/API/pleroma_api.md +++ b/docs/API/pleroma_api.md @@ -70,59 +70,6 @@ Request parameters can be passed via [query strings](https://en.wikipedia.org/wi * Response: JSON. Returns `{"status": "success"}` if the account was successfully disabled, `{"error": "[error message]"}` otherwise * Example response: `{"error": "Invalid password."}` -## `/api/account/register` -### Register a new user -* Method `POST` -* Authentication: not required -* Params: - * `nickname` - * `fullname` - * `bio` - * `email` - * `password` - * `confirm` - * `captcha_solution`: optional, contains provider-specific captcha solution, - * `captcha_token`: optional, contains provider-specific captcha token - * `token`: invite token required when the registrations aren't public. -* Response: JSON. Returns a user object on success, otherwise returns `{"error": "error_msg"}` -* Example response: -```json -{ - "background_image": null, - "cover_photo": "https://pleroma.soykaf.com/images/banner.png", - "created_at": "Tue Dec 18 16:55:56 +0000 2018", - "default_scope": "public", - "description": "blushy-crushy fediverse idol + pleroma dev\nlet's be friends \nぷれろまの生徒会長。謎の外人。日本語OK. \n公主病.", - "description_html": "blushy-crushy fediverse idol + pleroma dev.<br />let's be friends <br />ぷれろまの生徒会長。謎の外人。日本語OK. <br />公主病.", - "favourites_count": 0, - "fields": [], - "followers_count": 0, - "following": false, - "follows_you": false, - "friends_count": 0, - "id": 6, - "is_local": true, - "locked": false, - "name": "lain", - "name_html": "lain", - "no_rich_text": false, - "pleroma": { - "tags": [] - }, - "profile_image_url": "https://pleroma.soykaf.com/images/avi.png", - "profile_image_url_https": "https://pleroma.soykaf.com/images/avi.png", - "profile_image_url_original": "https://pleroma.soykaf.com/images/avi.png", - "profile_image_url_profile_size": "https://pleroma.soykaf.com/images/avi.png", - "rights": { - "delete_others_notice": false - }, - "screen_name": "lain", - "statuses_count": 0, - "statusnet_blocking": false, - "statusnet_profile_url": "https://pleroma.soykaf.com/users/lain" -} -``` - ## `/api/pleroma/admin/`… See [Admin-API](admin_api.md) @@ -485,30 +432,30 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa Emoji reactions work a lot like favourites do. They make it possible to react to a post with a single emoji character. -## `POST /api/v1/pleroma/statuses/:id/react_with_emoji` +## `PUT /api/v1/pleroma/statuses/:id/reactions/:emoji` ### React to a post with a unicode emoji -* Method: `POST` +* Method: `PUT` * Authentication: required * Params: `emoji`: A single character unicode emoji * Response: JSON, the status. -## `POST /api/v1/pleroma/statuses/:id/unreact_with_emoji` +## `DELETE /api/v1/pleroma/statuses/:id/reactions/:emoji` ### Remove a reaction to a post with a unicode emoji -* Method: `POST` +* Method: `DELETE` * Authentication: required * Params: `emoji`: A single character unicode emoji * Response: JSON, the status. -## `GET /api/v1/pleroma/statuses/:id/emoji_reactions_by` +## `GET /api/v1/pleroma/statuses/:id/reactions` ### Get an object of emoji to account mappings with accounts that reacted to the post * Method: `GET` * Authentication: optional * Params: None -* Response: JSON, a map of emoji to account list mappings. +* Response: JSON, a list of emoji/account list tuples, sorted by emoji insertion date, in ascending order, e.g, the first emoji in the list is the oldest. * Example Response: ```json -{ - "😀" => [{"id" => "xyz.."...}, {"id" => "zyx..."}], - "🗡" => [{"id" => "abc..."}] -} +[ + {"name": "😀", "count": 2, "me": true, "accounts": [{"id" => "xyz.."...}, {"id" => "zyx..."}]}, + {"name": "☕", "count": 1, "me": false, "accounts": [{"id" => "abc..."}]} +] ``` |