1 # Pleroma: A lightweight social networking server
2 # Copyright © 2017-2021 Pleroma Authors <https://pleroma.social/>
3 # SPDX-License-Identifier: AGPL-3.0-only
5 defmodule Pleroma.Web.ApiSpec.AccountOperation do
6 alias OpenApiSpex.Operation
7 alias OpenApiSpex.Reference
8 alias OpenApiSpex.Schema
9 alias Pleroma.Web.ApiSpec.Schemas.Account
10 alias Pleroma.Web.ApiSpec.Schemas.AccountRelationship
11 alias Pleroma.Web.ApiSpec.Schemas.ActorType
12 alias Pleroma.Web.ApiSpec.Schemas.ApiError
13 alias Pleroma.Web.ApiSpec.Schemas.BooleanLike
14 alias Pleroma.Web.ApiSpec.Schemas.List
15 alias Pleroma.Web.ApiSpec.Schemas.Status
16 alias Pleroma.Web.ApiSpec.Schemas.VisibilityScope
18 import Pleroma.Web.ApiSpec.Helpers
20 @spec open_api_operation(atom) :: Operation.t()
21 def open_api_operation(action) do
22 operation = String.to_existing_atom("#{action}_operation")
23 apply(__MODULE__, operation, [])
26 @spec create_operation() :: Operation.t()
27 def create_operation do
29 tags: ["Account credentials"],
30 summary: "Register an account",
32 "Creates a user and account records. Returns an account access token for the app that initiated the request. The app should save this token for later, and should wait for the user to confirm their account by clicking a link in their email inbox.",
33 operationId: "AccountController.create",
34 requestBody: request_body("Parameters", create_request(), required: true),
36 200 => Operation.response("Account", "application/json", create_response()),
37 400 => Operation.response("Error", "application/json", ApiError),
38 403 => Operation.response("Error", "application/json", ApiError),
39 429 => Operation.response("Error", "application/json", ApiError)
44 def verify_credentials_operation do
46 tags: ["Account credentials"],
47 description: "Test to make sure that the user token works.",
48 summary: "Verify account credentials",
49 operationId: "AccountController.verify_credentials",
50 security: [%{"oAuth" => ["read:accounts"]}],
52 200 => Operation.response("Account", "application/json", Account)
57 def update_credentials_operation do
59 tags: ["Account credentials"],
60 summary: "Update account credentials",
61 description: "Update the user's display and preferences.",
62 operationId: "AccountController.update_credentials",
63 security: [%{"oAuth" => ["write:accounts"]}],
64 requestBody: request_body("Parameters", update_credentials_request(), required: true),
66 200 => Operation.response("Account", "application/json", Account),
67 403 => Operation.response("Error", "application/json", ApiError)
72 def relationships_operation do
74 tags: ["Retrieve account information"],
75 summary: "Relationship with current account",
76 operationId: "AccountController.relationships",
77 description: "Find out whether a given account is followed, blocked, muted, etc.",
78 security: [%{"oAuth" => ["read:follows"]}],
84 oneOf: [%Schema{type: :array, items: %Schema{type: :string}}, %Schema{type: :string}]
91 200 => Operation.response("Account", "application/json", array_of_relationships())
98 tags: ["Retrieve account information"],
100 operationId: "AccountController.show",
101 description: "View information about a profile.",
103 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
104 with_relationships_param()
107 200 => Operation.response("Account", "application/json", Account),
108 401 => Operation.response("Error", "application/json", ApiError),
109 404 => Operation.response("Error", "application/json", ApiError)
114 def statuses_operation do
117 tags: ["Retrieve account information"],
118 operationId: "AccountController.statuses",
120 "Statuses posted to the given account. Public (for public statuses only), or user token + `read:statuses` (for private statuses the user is authorized to see)",
123 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
124 Operation.parameter(:pinned, :query, BooleanLike, "Include only pinned statuses"),
125 Operation.parameter(:tagged, :query, :string, "With tag"),
130 "Include only statuses with media attached"
136 "Include statuses from muted accounts."
138 Operation.parameter(:exclude_reblogs, :query, BooleanLike, "Exclude reblogs"),
139 Operation.parameter(:exclude_replies, :query, BooleanLike, "Exclude replies"),
141 :exclude_visibilities,
143 %Schema{type: :array, items: VisibilityScope},
144 "Exclude visibilities"
150 "Include reactions from muted accounts."
152 ] ++ pagination_params(),
154 200 => Operation.response("Statuses", "application/json", array_of_statuses()),
155 401 => Operation.response("Error", "application/json", ApiError),
156 404 => Operation.response("Error", "application/json", ApiError)
161 def followers_operation do
163 tags: ["Retrieve account information"],
164 summary: "Followers",
165 operationId: "AccountController.followers",
166 security: [%{"oAuth" => ["read:accounts"]}],
168 "Accounts which follow the given account, if network is not hidden by the account owner.",
170 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
171 Operation.parameter(:id, :query, :string, "ID of the resource owner"),
172 with_relationships_param() | pagination_params()
175 200 => Operation.response("Accounts", "application/json", array_of_accounts())
180 def following_operation do
182 tags: ["Retrieve account information"],
183 summary: "Following",
184 operationId: "AccountController.following",
185 security: [%{"oAuth" => ["read:accounts"]}],
187 "Accounts which the given account is following, if network is not hidden by the account owner.",
189 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
190 Operation.parameter(:id, :query, :string, "ID of the resource owner"),
191 with_relationships_param() | pagination_params()
193 responses: %{200 => Operation.response("Accounts", "application/json", array_of_accounts())}
197 def lists_operation do
199 tags: ["Retrieve account information"],
200 summary: "Lists containing this account",
201 operationId: "AccountController.lists",
202 security: [%{"oAuth" => ["read:lists"]}],
203 description: "User lists that you have added this account to.",
204 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
205 responses: %{200 => Operation.response("Lists", "application/json", array_of_lists())}
209 def follow_operation do
211 tags: ["Account actions"],
213 operationId: "AccountController.follow",
214 security: [%{"oAuth" => ["follow", "write:follows"]}],
215 description: "Follow the given account",
217 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"}
227 description: "Receive this account's reblogs in home timeline? Defaults to true.",
233 "Receive notifications for all statuses posted by the account? Defaults to false.",
241 200 => Operation.response("Relationship", "application/json", AccountRelationship),
242 400 => Operation.response("Error", "application/json", ApiError),
243 404 => Operation.response("Error", "application/json", ApiError)
248 def unfollow_operation do
250 tags: ["Account actions"],
252 operationId: "AccountController.unfollow",
253 security: [%{"oAuth" => ["follow", "write:follows"]}],
254 description: "Unfollow the given account",
255 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
257 200 => Operation.response("Relationship", "application/json", AccountRelationship),
258 400 => Operation.response("Error", "application/json", ApiError),
259 404 => Operation.response("Error", "application/json", ApiError)
264 def mute_operation do
266 tags: ["Account actions"],
268 operationId: "AccountController.mute",
269 security: [%{"oAuth" => ["follow", "write:mutes"]}],
270 requestBody: request_body("Parameters", mute_request()),
272 "Mute the given account. Clients should filter statuses and notifications from this account, if received (e.g. due to a boost in the Home timeline).",
274 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
278 %Schema{allOf: [BooleanLike], default: true},
279 "Mute notifications in addition to statuses? Defaults to `true`."
284 %Schema{type: :integer, default: 0},
285 "Expire the mute in `expires_in` seconds. Default 0 for infinity"
289 200 => Operation.response("Relationship", "application/json", AccountRelationship)
294 def unmute_operation do
296 tags: ["Account actions"],
298 operationId: "AccountController.unmute",
299 security: [%{"oAuth" => ["follow", "write:mutes"]}],
300 description: "Unmute the given account.",
301 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
303 200 => Operation.response("Relationship", "application/json", AccountRelationship)
308 def block_operation do
310 tags: ["Account actions"],
312 operationId: "AccountController.block",
313 security: [%{"oAuth" => ["follow", "write:blocks"]}],
315 "Block the given account. Clients should filter statuses from this account if received (e.g. due to a boost in the Home timeline)",
316 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
318 200 => Operation.response("Relationship", "application/json", AccountRelationship)
323 def unblock_operation do
325 tags: ["Account actions"],
327 operationId: "AccountController.unblock",
328 security: [%{"oAuth" => ["follow", "write:blocks"]}],
329 description: "Unblock the given account.",
330 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
332 200 => Operation.response("Relationship", "application/json", AccountRelationship)
337 def follow_by_uri_operation do
339 tags: ["Account actions"],
340 summary: "Follow by URI",
341 operationId: "AccountController.follows",
342 security: [%{"oAuth" => ["follow", "write:follows"]}],
343 requestBody: request_body("Parameters", follow_by_uri_request(), required: true),
345 200 => Operation.response("Account", "application/json", AccountRelationship),
346 400 => Operation.response("Error", "application/json", ApiError),
347 404 => Operation.response("Error", "application/json", ApiError)
352 def mutes_operation do
354 tags: ["Blocks and mutes"],
355 summary: "Retrieve list of mutes",
356 operationId: "AccountController.mutes",
357 description: "Accounts the user has muted.",
358 security: [%{"oAuth" => ["follow", "read:mutes"]}],
359 parameters: [with_relationships_param() | pagination_params()],
361 200 => Operation.response("Accounts", "application/json", array_of_accounts())
366 def blocks_operation do
368 tags: ["Blocks and mutes"],
369 summary: "Retrieve list of blocks",
370 operationId: "AccountController.blocks",
371 description: "View your blocks. See also accounts/:id/{block,unblock}",
372 security: [%{"oAuth" => ["read:blocks"]}],
373 parameters: pagination_params(),
375 200 => Operation.response("Accounts", "application/json", array_of_accounts())
380 def endorsements_operation do
382 tags: ["Retrieve account information"],
383 summary: "Endorsements",
384 operationId: "AccountController.endorsements",
385 description: "Not implemented",
386 security: [%{"oAuth" => ["read:accounts"]}],
388 200 => empty_array_response()
393 def identity_proofs_operation do
395 tags: ["Retrieve account information"],
396 summary: "Identity proofs",
397 operationId: "AccountController.identity_proofs",
398 # Validators complains about unused path params otherwise
400 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"}
402 description: "Not implemented",
404 200 => empty_array_response()
409 defp create_request do
411 title: "AccountCreateRequest",
412 description: "POST body for creating an account",
414 required: [:username, :password, :agreement],
420 "Text that will be reviewed by moderators if registrations require manual approval"
422 username: %Schema{type: :string, description: "The desired username for the account"},
427 "The email address to be used for login. Required when `account_activation_required` is enabled.",
432 description: "The password to be used for login",
436 allOf: [BooleanLike],
438 "Whether the user agrees to the local rules, terms, and policies. These should be presented to the user in order to allow them to consent before setting this parameter to TRUE."
443 description: "The language of the confirmation email that will be sent"
445 # Pleroma-specific properties:
446 fullname: %Schema{type: :string, nullable: true, description: "Full name"},
447 bio: %Schema{type: :string, description: "Bio", nullable: true, default: ""},
448 captcha_solution: %Schema{
451 description: "Provider-specific captcha solution"
453 captcha_token: %Schema{
456 description: "Provider-specific captcha token"
458 captcha_answer_data: %Schema{
461 description: "Provider-specific captcha data"
466 description: "Invite token required when the registrations aren't public"
470 "username" => "cofe",
471 "email" => "cofe@example.com",
472 "password" => "secret",
473 "agreement" => "true",
479 # Note: this is a token response (if login succeeds!), but there's no oauth operation file yet.
480 defp create_response do
482 title: "AccountCreateResponse",
483 description: "Response schema for an account",
486 # The response when auto-login on create succeeds (token is issued):
487 token_type: %Schema{type: :string},
488 access_token: %Schema{type: :string},
489 refresh_token: %Schema{type: :string},
490 scope: %Schema{type: :string},
491 created_at: %Schema{type: :integer, format: :"date-time"},
492 me: %Schema{type: :string},
493 expires_in: %Schema{type: :integer},
495 # The response when registration succeeds but auto-login fails (no token):
496 identifier: %Schema{type: :string},
497 message: %Schema{type: :string}
499 # Note: example of successful registration with failed login response:
501 # "identifier" => "missing_confirmed_email",
502 # "message" => "You have been registered. Please check your email for further instructions."
505 "token_type" => "Bearer",
506 "access_token" => "i9hAVVzGld86Pl5JtLtizKoXVvtTlSCJvwaugCxvZzk",
507 "refresh_token" => "i9hAVVzGld86Pl5JtLtizKoXVvtTlSCJvwaugCxvZzz",
508 "created_at" => 1_585_918_714,
510 "scope" => "read write follow push",
511 "me" => "https://gensokyo.2hu/users/raymoo"
516 defp update_credentials_request do
518 title: "AccountUpdateCredentialsRequest",
519 description: "POST body for creating an account",
523 allOf: [BooleanLike],
525 description: "Whether the account has a bot flag."
527 display_name: %Schema{
530 description: "The display name to use for the profile."
532 note: %Schema{type: :string, description: "The account bio."},
536 description: "Avatar image encoded using multipart/form-data",
542 description: "Header image encoded using multipart/form-data",
546 allOf: [BooleanLike],
548 description: "Whether manual approval of follow requests is required."
550 accepts_chat_messages: %Schema{
551 allOf: [BooleanLike],
553 description: "Whether the user accepts receiving chat messages."
555 fields_attributes: %Schema{
558 %Schema{type: :array, items: attribute_field()},
559 %Schema{type: :object, additionalProperties: attribute_field()}
562 # NOTE: `source` field is not supported
567 # privacy: %Schema{type: :string},
568 # sensitive: %Schema{type: :boolean},
569 # language: %Schema{type: :string}
573 # Pleroma-specific fields
574 no_rich_text: %Schema{
575 allOf: [BooleanLike],
577 description: "html tags are stripped from all statuses requested from the API"
579 hide_followers: %Schema{
580 allOf: [BooleanLike],
582 description: "user's followers will be hidden"
584 hide_follows: %Schema{
585 allOf: [BooleanLike],
587 description: "user's follows will be hidden"
589 hide_followers_count: %Schema{
590 allOf: [BooleanLike],
592 description: "user's follower count will be hidden"
594 hide_follows_count: %Schema{
595 allOf: [BooleanLike],
597 description: "user's follow count will be hidden"
599 hide_favorites: %Schema{
600 allOf: [BooleanLike],
602 description: "user's favorites timeline will be hidden"
605 allOf: [BooleanLike],
607 description: "user's role (e.g admin, moderator) will be exposed to anyone in the
610 default_scope: VisibilityScope,
611 pleroma_settings_store: %Schema{
614 description: "Opaque user settings to be saved on the backend."
616 skip_thread_containment: %Schema{
617 allOf: [BooleanLike],
619 description: "Skip filtering out broken threads"
621 allow_following_move: %Schema{
622 allOf: [BooleanLike],
624 description: "Allows automatically follow moved following accounts"
626 also_known_as: %Schema{
628 items: %Schema{type: :string},
630 description: "List of alternate ActivityPub IDs"
632 pleroma_background_image: %Schema{
635 description: "Sets the background image of the user.",
638 discoverable: %Schema{
639 allOf: [BooleanLike],
642 "Discovery (listing, indexing) of this account by external services (search bots etc.) is allowed."
644 actor_type: ActorType
648 display_name: "cofe",
650 fields_attributes: [%{name: "foo", value: "bar"}],
652 hide_followers: true,
654 hide_followers_count: false,
655 hide_follows_count: false,
656 hide_favorites: false,
658 default_scope: "private",
659 pleroma_settings_store: %{"pleroma-fe" => %{"key" => "val"}},
660 skip_thread_containment: false,
661 allow_following_move: false,
662 also_known_as: ["https://foo.bar/users/foo"],
669 def array_of_accounts do
671 title: "ArrayOfAccounts",
674 example: [Account.schema().example]
678 defp array_of_relationships do
680 title: "ArrayOfRelationships",
681 description: "Response schema for account relationships",
683 items: AccountRelationship,
688 "showing_reblogs" => true,
689 "followed_by" => true,
691 "blocked_by" => true,
693 "muting_notifications" => false,
694 "requested" => false,
695 "domain_blocking" => false,
696 "subscribing" => false,
702 "showing_reblogs" => true,
703 "followed_by" => true,
705 "blocked_by" => true,
707 "muting_notifications" => false,
709 "domain_blocking" => false,
710 "subscribing" => false,
716 "showing_reblogs" => true,
717 "followed_by" => true,
719 "blocked_by" => false,
721 "muting_notifications" => false,
722 "requested" => false,
723 "domain_blocking" => true,
724 "subscribing" => true,
731 defp follow_by_uri_request do
733 title: "AccountFollowsRequest",
734 description: "POST body for muting an account",
737 uri: %Schema{type: :string, nullable: true, format: :uri}
745 title: "AccountMuteRequest",
746 description: "POST body for muting an account",
749 notifications: %Schema{
750 allOf: [BooleanLike],
752 description: "Mute notifications in addition to statuses? Defaults to true.",
758 description: "Expire the mute in `expires_in` seconds. Default 0 for infinity",
763 "notifications" => true,
764 "expires_in" => 86_400
769 defp array_of_lists do
771 title: "ArrayOfLists",
772 description: "Response schema for lists",
776 %{"id" => "123", "title" => "my list"},
777 %{"id" => "1337", "title" => "anotehr list"}
782 defp array_of_statuses do
784 title: "ArrayOfStatuses",
790 defp attribute_field do
792 title: "AccountAttributeField",
793 description: "Request schema for account custom fields",
796 name: %Schema{type: :string},
797 value: %Schema{type: :string}
799 required: [:name, :value],
802 "value" => "https://pleroma.com"