Merge branch '2317-old-reset-tokens' into 'develop'
[akkoma] / lib / pleroma / web / api_spec / operations / status_operation.ex
1 # Pleroma: A lightweight social networking server
2 # Copyright © 2017-2020 Pleroma Authors <https://pleroma.social/>
3 # SPDX-License-Identifier: AGPL-3.0-only
4
5 defmodule Pleroma.Web.ApiSpec.StatusOperation do
6 alias OpenApiSpex.Operation
7 alias OpenApiSpex.Schema
8 alias Pleroma.Web.ApiSpec.AccountOperation
9 alias Pleroma.Web.ApiSpec.Schemas.ApiError
10 alias Pleroma.Web.ApiSpec.Schemas.BooleanLike
11 alias Pleroma.Web.ApiSpec.Schemas.FlakeID
12 alias Pleroma.Web.ApiSpec.Schemas.ScheduledStatus
13 alias Pleroma.Web.ApiSpec.Schemas.Status
14 alias Pleroma.Web.ApiSpec.Schemas.VisibilityScope
15
16 import Pleroma.Web.ApiSpec.Helpers
17
18 def open_api_operation(action) do
19 operation = String.to_existing_atom("#{action}_operation")
20 apply(__MODULE__, operation, [])
21 end
22
23 def index_operation do
24 %Operation{
25 tags: ["Statuses"],
26 summary: "Get multiple statuses by IDs",
27 security: [%{"oAuth" => ["read:statuses"]}],
28 parameters: [
29 Operation.parameter(
30 :ids,
31 :query,
32 %Schema{type: :array, items: FlakeID},
33 "Array of status IDs"
34 ),
35 Operation.parameter(
36 :with_muted,
37 :query,
38 BooleanLike,
39 "Include reactions from muted acccounts."
40 )
41 ],
42 operationId: "StatusController.index",
43 responses: %{
44 200 => Operation.response("Array of Status", "application/json", array_of_statuses())
45 }
46 }
47 end
48
49 def create_operation do
50 %Operation{
51 tags: ["Statuses"],
52 summary: "Publish new status",
53 security: [%{"oAuth" => ["write:statuses"]}],
54 description: "Post a new status",
55 operationId: "StatusController.create",
56 requestBody: request_body("Parameters", create_request(), required: true),
57 responses: %{
58 200 =>
59 Operation.response(
60 "Status. When `scheduled_at` is present, ScheduledStatus is returned instead",
61 "application/json",
62 %Schema{oneOf: [Status, ScheduledStatus]}
63 ),
64 422 => Operation.response("Bad Request / MRF Rejection", "application/json", ApiError)
65 }
66 }
67 end
68
69 def show_operation do
70 %Operation{
71 tags: ["Statuses"],
72 summary: "View specific status",
73 description: "View information about a status",
74 operationId: "StatusController.show",
75 security: [%{"oAuth" => ["read:statuses"]}],
76 parameters: [
77 id_param(),
78 Operation.parameter(
79 :with_muted,
80 :query,
81 BooleanLike,
82 "Include reactions from muted acccounts."
83 )
84 ],
85 responses: %{
86 200 => status_response(),
87 404 => Operation.response("Not Found", "application/json", ApiError)
88 }
89 }
90 end
91
92 def delete_operation do
93 %Operation{
94 tags: ["Statuses"],
95 summary: "Delete status",
96 security: [%{"oAuth" => ["write:statuses"]}],
97 description: "Delete one of your own statuses",
98 operationId: "StatusController.delete",
99 parameters: [id_param()],
100 responses: %{
101 200 => status_response(),
102 403 => Operation.response("Forbidden", "application/json", ApiError),
103 404 => Operation.response("Not Found", "application/json", ApiError)
104 }
105 }
106 end
107
108 def reblog_operation do
109 %Operation{
110 tags: ["Statuses"],
111 summary: "Boost",
112 security: [%{"oAuth" => ["write:statuses"]}],
113 description: "Share a status",
114 operationId: "StatusController.reblog",
115 parameters: [id_param()],
116 requestBody:
117 request_body("Parameters", %Schema{
118 type: :object,
119 properties: %{
120 visibility: %Schema{allOf: [VisibilityScope], default: "public"}
121 }
122 }),
123 responses: %{
124 200 => status_response(),
125 404 => Operation.response("Not Found", "application/json", ApiError)
126 }
127 }
128 end
129
130 def unreblog_operation do
131 %Operation{
132 tags: ["Statuses"],
133 summary: "Undo boost",
134 security: [%{"oAuth" => ["write:statuses"]}],
135 description: "Undo a reshare of a status",
136 operationId: "StatusController.unreblog",
137 parameters: [id_param()],
138 responses: %{
139 200 => status_response(),
140 404 => Operation.response("Not Found", "application/json", ApiError)
141 }
142 }
143 end
144
145 def favourite_operation do
146 %Operation{
147 tags: ["Statuses"],
148 summary: "Favourite",
149 security: [%{"oAuth" => ["write:favourites"]}],
150 description: "Add a status to your favourites list",
151 operationId: "StatusController.favourite",
152 parameters: [id_param()],
153 responses: %{
154 200 => status_response(),
155 404 => Operation.response("Not Found", "application/json", ApiError)
156 }
157 }
158 end
159
160 def unfavourite_operation do
161 %Operation{
162 tags: ["Statuses"],
163 summary: "Undo favourite",
164 security: [%{"oAuth" => ["write:favourites"]}],
165 description: "Remove a status from your favourites list",
166 operationId: "StatusController.unfavourite",
167 parameters: [id_param()],
168 responses: %{
169 200 => status_response(),
170 404 => Operation.response("Not Found", "application/json", ApiError)
171 }
172 }
173 end
174
175 def pin_operation do
176 %Operation{
177 tags: ["Statuses"],
178 summary: "Pin to profile",
179 security: [%{"oAuth" => ["write:accounts"]}],
180 description: "Feature one of your own public statuses at the top of your profile",
181 operationId: "StatusController.pin",
182 parameters: [id_param()],
183 responses: %{
184 200 => status_response(),
185 400 => Operation.response("Error", "application/json", ApiError)
186 }
187 }
188 end
189
190 def unpin_operation do
191 %Operation{
192 tags: ["Statuses"],
193 summary: "Unpin to profile",
194 security: [%{"oAuth" => ["write:accounts"]}],
195 description: "Unfeature a status from the top of your profile",
196 operationId: "StatusController.unpin",
197 parameters: [id_param()],
198 responses: %{
199 200 => status_response(),
200 400 => Operation.response("Error", "application/json", ApiError)
201 }
202 }
203 end
204
205 def bookmark_operation do
206 %Operation{
207 tags: ["Statuses"],
208 summary: "Bookmark",
209 security: [%{"oAuth" => ["write:bookmarks"]}],
210 description: "Privately bookmark a status",
211 operationId: "StatusController.bookmark",
212 parameters: [id_param()],
213 responses: %{
214 200 => status_response()
215 }
216 }
217 end
218
219 def unbookmark_operation do
220 %Operation{
221 tags: ["Statuses"],
222 summary: "Undo bookmark",
223 security: [%{"oAuth" => ["write:bookmarks"]}],
224 description: "Remove a status from your private bookmarks",
225 operationId: "StatusController.unbookmark",
226 parameters: [id_param()],
227 responses: %{
228 200 => status_response()
229 }
230 }
231 end
232
233 def mute_conversation_operation do
234 %Operation{
235 tags: ["Statuses"],
236 summary: "Mute conversation",
237 security: [%{"oAuth" => ["write:mutes"]}],
238 description: "Do not receive notifications for the thread that this status is part of.",
239 operationId: "StatusController.mute_conversation",
240 requestBody:
241 request_body("Parameters", %Schema{
242 type: :object,
243 properties: %{
244 expires_in: %Schema{
245 type: :integer,
246 nullable: true,
247 description: "Expire the mute in `expires_in` seconds. Default 0 for infinity",
248 default: 0
249 }
250 }
251 }),
252 parameters: [
253 id_param(),
254 Operation.parameter(
255 :expires_in,
256 :query,
257 %Schema{type: :integer, default: 0},
258 "Expire the mute in `expires_in` seconds. Default 0 for infinity"
259 )
260 ],
261 responses: %{
262 200 => status_response(),
263 400 => Operation.response("Error", "application/json", ApiError)
264 }
265 }
266 end
267
268 def unmute_conversation_operation do
269 %Operation{
270 tags: ["Statuses"],
271 summary: "Unmute conversation",
272 security: [%{"oAuth" => ["write:mutes"]}],
273 description:
274 "Start receiving notifications again for the thread that this status is part of",
275 operationId: "StatusController.unmute_conversation",
276 parameters: [id_param()],
277 responses: %{
278 200 => status_response(),
279 400 => Operation.response("Error", "application/json", ApiError)
280 }
281 }
282 end
283
284 def card_operation do
285 %Operation{
286 tags: ["Statuses"],
287 deprecated: true,
288 summary: "Preview card",
289 description: "Deprecated in favor of card property inlined on Status entity",
290 operationId: "StatusController.card",
291 parameters: [id_param()],
292 security: [%{"oAuth" => ["read:statuses"]}],
293 responses: %{
294 200 =>
295 Operation.response("Card", "application/json", %Schema{
296 type: :object,
297 nullable: true,
298 properties: %{
299 type: %Schema{type: :string, enum: ["link", "photo", "video", "rich"]},
300 provider_name: %Schema{type: :string, nullable: true},
301 provider_url: %Schema{type: :string, format: :uri},
302 url: %Schema{type: :string, format: :uri},
303 image: %Schema{type: :string, nullable: true, format: :uri},
304 title: %Schema{type: :string},
305 description: %Schema{type: :string}
306 }
307 })
308 }
309 }
310 end
311
312 def favourited_by_operation do
313 %Operation{
314 tags: ["Statuses"],
315 summary: "Favourited by",
316 description: "View who favourited a given status",
317 operationId: "StatusController.favourited_by",
318 security: [%{"oAuth" => ["read:accounts"]}],
319 parameters: [id_param()],
320 responses: %{
321 200 =>
322 Operation.response(
323 "Array of Accounts",
324 "application/json",
325 AccountOperation.array_of_accounts()
326 ),
327 404 => Operation.response("Not Found", "application/json", ApiError)
328 }
329 }
330 end
331
332 def reblogged_by_operation do
333 %Operation{
334 tags: ["Statuses"],
335 summary: "Boosted by",
336 description: "View who boosted a given status",
337 operationId: "StatusController.reblogged_by",
338 security: [%{"oAuth" => ["read:accounts"]}],
339 parameters: [id_param()],
340 responses: %{
341 200 =>
342 Operation.response(
343 "Array of Accounts",
344 "application/json",
345 AccountOperation.array_of_accounts()
346 ),
347 404 => Operation.response("Not Found", "application/json", ApiError)
348 }
349 }
350 end
351
352 def context_operation do
353 %Operation{
354 tags: ["Statuses"],
355 summary: "Parent and child statuses",
356 description: "View statuses above and below this status in the thread",
357 operationId: "StatusController.context",
358 security: [%{"oAuth" => ["read:statuses"]}],
359 parameters: [id_param()],
360 responses: %{
361 200 => Operation.response("Context", "application/json", context())
362 }
363 }
364 end
365
366 def favourites_operation do
367 %Operation{
368 tags: ["Statuses"],
369 summary: "Favourited statuses",
370 description:
371 "Statuses the user has favourited. Please note that you have to use the link headers to paginate this. You can not build the query parameters yourself.",
372 operationId: "StatusController.favourites",
373 parameters: pagination_params(),
374 security: [%{"oAuth" => ["read:favourites"]}],
375 responses: %{
376 200 => Operation.response("Array of Statuses", "application/json", array_of_statuses())
377 }
378 }
379 end
380
381 def bookmarks_operation do
382 %Operation{
383 tags: ["Statuses"],
384 summary: "Bookmarked statuses",
385 description: "Statuses the user has bookmarked",
386 operationId: "StatusController.bookmarks",
387 parameters: pagination_params(),
388 security: [%{"oAuth" => ["read:bookmarks"]}],
389 responses: %{
390 200 => Operation.response("Array of Statuses", "application/json", array_of_statuses())
391 }
392 }
393 end
394
395 def array_of_statuses do
396 %Schema{type: :array, items: Status, example: [Status.schema().example]}
397 end
398
399 defp create_request do
400 %Schema{
401 title: "StatusCreateRequest",
402 type: :object,
403 properties: %{
404 status: %Schema{
405 type: :string,
406 nullable: true,
407 description:
408 "Text content of the status. If `media_ids` is provided, this becomes optional. Attaching a `poll` is optional while `status` is provided."
409 },
410 media_ids: %Schema{
411 nullable: true,
412 type: :array,
413 items: %Schema{type: :string},
414 description: "Array of Attachment ids to be attached as media."
415 },
416 poll: %Schema{
417 nullable: true,
418 type: :object,
419 required: [:options],
420 properties: %{
421 options: %Schema{
422 type: :array,
423 items: %Schema{type: :string},
424 description: "Array of possible answers. Must be provided with `poll[expires_in]`."
425 },
426 expires_in: %Schema{
427 type: :integer,
428 nullable: true,
429 description:
430 "Duration the poll should be open, in seconds. Must be provided with `poll[options]`"
431 },
432 multiple: %Schema{
433 allOf: [BooleanLike],
434 nullable: true,
435 description: "Allow multiple choices?"
436 },
437 hide_totals: %Schema{
438 allOf: [BooleanLike],
439 nullable: true,
440 description: "Hide vote counts until the poll ends?"
441 }
442 }
443 },
444 in_reply_to_id: %Schema{
445 nullable: true,
446 allOf: [FlakeID],
447 description: "ID of the status being replied to, if status is a reply"
448 },
449 sensitive: %Schema{
450 allOf: [BooleanLike],
451 nullable: true,
452 description: "Mark status and attached media as sensitive?"
453 },
454 spoiler_text: %Schema{
455 type: :string,
456 nullable: true,
457 description:
458 "Text to be shown as a warning or subject before the actual content. Statuses are generally collapsed behind this field."
459 },
460 scheduled_at: %Schema{
461 type: :string,
462 format: :"date-time",
463 nullable: true,
464 description:
465 "ISO 8601 Datetime at which to schedule a status. Providing this paramter will cause ScheduledStatus to be returned instead of Status. Must be at least 5 minutes in the future."
466 },
467 language: %Schema{
468 type: :string,
469 nullable: true,
470 description: "ISO 639 language code for this status."
471 },
472 # Pleroma-specific properties:
473 preview: %Schema{
474 allOf: [BooleanLike],
475 nullable: true,
476 description:
477 "If set to `true` the post won't be actually posted, but the status entitiy would still be rendered back. This could be useful for previewing rich text/custom emoji, for example"
478 },
479 content_type: %Schema{
480 type: :string,
481 nullable: true,
482 description:
483 "The MIME type of the status, it is transformed into HTML by the backend. You can get the list of the supported MIME types with the nodeinfo endpoint."
484 },
485 to: %Schema{
486 type: :array,
487 nullable: true,
488 items: %Schema{type: :string},
489 description:
490 "A list of nicknames (like `lain@soykaf.club` or `lain` on the local server) that will be used to determine who is going to be addressed by this post. Using this will disable the implicit addressing by mentioned names in the `status` body, only the people in the `to` list will be addressed. The normal rules for for post visibility are not affected by this and will still apply"
491 },
492 visibility: %Schema{
493 nullable: true,
494 anyOf: [
495 VisibilityScope,
496 %Schema{type: :string, description: "`list:LIST_ID`", example: "LIST:123"}
497 ],
498 description:
499 "Visibility of the posted status. Besides standard MastoAPI values (`direct`, `private`, `unlisted` or `public`) it can be used to address a List by setting it to `list:LIST_ID`"
500 },
501 expires_in: %Schema{
502 nullable: true,
503 type: :integer,
504 description:
505 "The number of seconds the posted activity should expire in. When a posted activity expires it will be deleted from the server, and a delete request for it will be federated. This needs to be longer than an hour."
506 },
507 in_reply_to_conversation_id: %Schema{
508 nullable: true,
509 type: :string,
510 description:
511 "Will reply to a given conversation, addressing only the people who are part of the recipient set of that conversation. Sets the visibility to `direct`."
512 }
513 },
514 example: %{
515 "status" => "What time is it?",
516 "sensitive" => "false",
517 "poll" => %{
518 "options" => ["Cofe", "Adventure"],
519 "expires_in" => 420
520 }
521 }
522 }
523 end
524
525 def id_param do
526 Operation.parameter(:id, :path, FlakeID, "Status ID",
527 example: "9umDrYheeY451cQnEe",
528 required: true
529 )
530 end
531
532 defp status_response do
533 Operation.response("Status", "application/json", Status)
534 end
535
536 defp context do
537 %Schema{
538 title: "StatusContext",
539 description:
540 "Represents the tree around a given status. Used for reconstructing threads of statuses.",
541 type: :object,
542 required: [:ancestors, :descendants],
543 properties: %{
544 ancestors: array_of_statuses(),
545 descendants: array_of_statuses()
546 },
547 example: %{
548 "ancestors" => [Status.schema().example],
549 "descendants" => [Status.schema().example]
550 }
551 }
552 end
553 end