Merge branch 'develop' of https://git.pleroma.social/pleroma/pleroma into develop
[akkoma] / docs / development / ap_extensions.md
1 # AP Extensions
2 ## Actor endpoints
3
4 The following endpoints are additionally present into our actors.
5
6 - `oauthRegistrationEndpoint` (`http://litepub.social/ns#oauthRegistrationEndpoint`)
7 - `uploadMedia` (`https://www.w3.org/ns/activitystreams#uploadMedia`)
8
9 ### oauthRegistrationEndpoint
10
11 Points to MastodonAPI `/api/v1/apps` for now.
12
13 See <https://docs.joinmastodon.org/methods/apps/>
14
15 ### uploadMedia
16
17 Inspired by <https://www.w3.org/wiki/SocialCG/ActivityPub/MediaUpload>, it is part of the ActivityStreams namespace because it used to be part of the ActivityPub specification and got removed from it.
18
19 Content-Type: multipart/form-data
20
21 Parameters:
22 - (required) `file`: The file being uploaded
23 - (optionnal) `description`: A plain-text description of the media, for accessibility purposes.
24
25 Response: HTTP 201 Created with the object into the body, no `Location` header provided as it doesn't have an `id`
26
27 The object given in the reponse should then be inserted into an Object's `attachment` field.
28
29 ## ChatMessages
30
31 `ChatMessage`s are the messages sent in 1-on-1 chats. They are similar to
32 `Note`s, but the addresing is done by having a single AP actor in the `to`
33 field. Addressing multiple actors is not allowed. These messages are always
34 private, there is no public version of them. They are created with a `Create`
35 activity.
36
37 They are part of the `litepub` namespace as `http://litepub.social/ns#ChatMessage`.
38
39 Example:
40
41 ```json
42 {
43 "actor": "http://2hu.gensokyo/users/raymoo",
44 "id": "http://2hu.gensokyo/objects/1",
45 "object": {
46 "attributedTo": "http://2hu.gensokyo/users/raymoo",
47 "content": "You expected a cute girl? Too bad.",
48 "id": "http://2hu.gensokyo/objects/2",
49 "published": "2020-02-12T14:08:20Z",
50 "to": [
51 "http://2hu.gensokyo/users/marisa"
52 ],
53 "type": "ChatMessage"
54 },
55 "published": "2018-02-12T14:08:20Z",
56 "to": [
57 "http://2hu.gensokyo/users/marisa"
58 ],
59 "type": "Create"
60 }
61 ```
62
63 This setup does not prevent multi-user chats, but these will have to go through
64 a `Group`, which will be the recipient of the messages and then `Announce` them
65 to the users in the `Group`.