diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api/swagger.yaml | 22 | ||||
| -rw-r--r-- | docs/federation/federating_with_gotosocial.md | 106 | ||||
| -rw-r--r-- | docs/user_guide/settings.md | 24 |
3 files changed, 116 insertions, 36 deletions
diff --git a/docs/api/swagger.yaml b/docs/api/swagger.yaml index e17e3f479..b5eca23c6 100644 --- a/docs/api/swagger.yaml +++ b/docs/api/swagger.yaml @@ -225,7 +225,9 @@ definitions: type: array x-go-name: Emojis enable_rss: - description: Account has enabled RSS feed. + description: |- + Account has enabled RSS feed. + Key/value omitted if false. type: boolean x-go-name: EnableRSS fields: @@ -256,6 +258,12 @@ definitions: example: https://example.org/media/some_user/header/static/header.png type: string x-go-name: HeaderStatic + hide_collections: + description: |- + Account has opted to hide their followers/following collections. + Key/value omitted if false. + type: boolean + x-go-name: HideCollections id: description: The account id. example: 01FBVD42CQ3ZEEVMW180SBX03B @@ -2898,6 +2906,8 @@ paths: ``` <https://example.org/api/v1/accounts/0657WMDEC3KQDTD6NZ4XJZBK4M/followers?limit=80&max_id=01FC0SKA48HNSVR6YKZCQGS2V8>; rel="next", <https://example.org/api/v1/accounts/0657WMDEC3KQDTD6NZ4XJZBK4M/followers?limit=80&min_id=01FC0SKW5JK2Q4EVAV2B462YY0>; rel="prev" ```` + + If account `hide_collections` is true, and requesting account != target account, no results will be returned. operationId: accountFollowers parameters: - description: Account ID. @@ -2962,6 +2972,8 @@ paths: ``` <https://example.org/api/v1/accounts/0657WMDEC3KQDTD6NZ4XJZBK4M/following?limit=80&max_id=01FC0SKA48HNSVR6YKZCQGS2V8>; rel="next", <https://example.org/api/v1/accounts/0657WMDEC3KQDTD6NZ4XJZBK4M/following?limit=80&min_id=01FC0SKW5JK2Q4EVAV2B462YY0>; rel="prev" ```` + + If account `hide_collections` is true, and requesting account != target account, no results will be returned. operationId: accountFollowing parameters: - description: Account ID. @@ -3552,6 +3564,10 @@ paths: in: formData name: source[status_content_type] type: string + - description: FileName of the theme to use when rendering this account's profile or statuses. The theme must exist on this server, as indicated by /api/v1/accounts/themes. Empty string unsets theme and returns to the default GoToSocial theme. + in: formData + name: theme + type: string - description: Custom CSS to use when rendering this account's profile or statuses. String must be no more than 5,000 characters (~5kb). in: formData name: custom_css @@ -3560,6 +3576,10 @@ paths: in: formData name: enable_rss type: boolean + - description: Hide the account's following/followers collections. + in: formData + name: hide_collections + type: boolean - description: Name of 1st profile field to be added to this account's profile. (The index may be any string; add more indexes to send more fields.) in: formData name: fields_attributes[0][name] diff --git a/docs/federation/federating_with_gotosocial.md b/docs/federation/federating_with_gotosocial.md index dad673484..947a03f9b 100644 --- a/docs/federation/federating_with_gotosocial.md +++ b/docs/federation/federating_with_gotosocial.md @@ -106,7 +106,9 @@ This ensures that remote servers cannot flood a GoToSocial instance with spuriou For more details on request throttling and rate limiting behavior, please see the [throttling](../api/throttling.md) and [rate limiting](../api/ratelimiting.md) documents. -## Inbox +## Actors and Actor Properties + +### Inbox GoToSocial implements Inboxes for Actors following the ActivityPub specification [here](https://www.w3.org/TR/activitypub/#inbox). @@ -132,7 +134,7 @@ Invalidly-formed Inbox POST requests will receive a [400 - Bad Request](https:// Even if GoToSocial returns a `202` status code, it may not continue processing the Activity delivered, depending on the originator(s), target(s) and type of the Activity. ActivityPub is an extensive protocol, and GoToSocial does not cover every combination of Activity and Object. -## Outbox +### Outbox GoToSocial implements Outboxes for Actors (ie., instance accounts) following the ActivityPub specification [here](https://www.w3.org/TR/activitypub/#outbox). @@ -142,10 +144,10 @@ The server will return an OrderedCollection of the following structure: ```json { - "@context": "https://www.w3.org/ns/activitystreams", - "id": "https://example.org/users/whatever/outbox", - "type": "OrderedCollection", - "first": "https://example.org/users/whatever/outbox?page=true" + "@context": "https://www.w3.org/ns/activitystreams", + "id": "https://example.org/users/whatever/outbox", + "type": "OrderedCollection", + "first": "https://example.org/users/whatever/outbox?page=true" } ``` @@ -153,26 +155,26 @@ Note that the `OrderedCollection` itself contains no items. Callers must derefer ```json { - "id": "https://example.org/users/whatever/outbox?page=true", - "type": "OrderedCollectionPage", - "next": "https://example.org/users/whatever/outbox?max_id=01FJC1Q0E3SSQR59TD2M1KP4V8&page=true", - "prev": "https://example.org/users/whatever/outbox?min_id=01FJC1Q0E3SSQR59TD2M1KP4V8&page=true", - "partOf": "https://example.org/users/whatever/outbox", - "orderedItems": [ - { - "id": "https://example.org/users/whatever/statuses/01FJC1MKPVX2VMWP2ST93Q90K7/activity", - "type": "Create", - "actor": "https://example.org/users/whatever", - "published": "2021-10-18T20:06:18Z", - "to": [ - "https://www.w3.org/ns/activitystreams#Public" - ], - "cc": [ - "https://example.org/users/whatever/followers" - ], - "object": "https://example.org/users/whatever/statuses/01FJC1MKPVX2VMWP2ST93Q90K7" - } - ] + "id": "https://example.org/users/whatever/outbox?page=true", + "type": "OrderedCollectionPage", + "next": "https://example.org/users/whatever/outbox?max_id=01FJC1Q0E3SSQR59TD2M1KP4V8&page=true", + "prev": "https://example.org/users/whatever/outbox?min_id=01FJC1Q0E3SSQR59TD2M1KP4V8&page=true", + "partOf": "https://example.org/users/whatever/outbox", + "orderedItems": [ + { + "id": "https://example.org/users/whatever/statuses/01FJC1MKPVX2VMWP2ST93Q90K7/activity", + "type": "Create", + "actor": "https://example.org/users/whatever", + "published": "2021-10-18T20:06:18Z", + "to": [ + "https://www.w3.org/ns/activitystreams#Public" + ], + "cc": [ + "https://example.org/users/whatever/followers" + ], + "object": "https://example.org/users/whatever/statuses/01FJC1MKPVX2VMWP2ST93Q90K7" + } + ] } ``` @@ -180,6 +182,58 @@ The `orderedItems` array will contain up to 30 entries. To get more entries beyo Note that in the returned `orderedItems`, all activity types will be `Create`. On each activity, the `object` field will be the AP URI of an original public status created by the Actor who owns the Outbox (ie., a `Note` with `https://www.w3.org/ns/activitystreams#Public` in the `to` field, which is not a reply to another status). Callers can use the returned AP URIs to dereference the content of the notes. +### Followers / Following Collections + +GoToSocial implements followers and following collections as `OrderedCollection`s. A properly-signed `GET` request to an Actor's Following collection, for example, will return something like: + +```json +{ + "@context": "https://www.w3.org/ns/activitystreams", + "first": "https://example.org/users/someone/following?limit=40", + "id": "https://example.org/users/someone/following", + "totalItems": 397, + "type": "OrderedCollection" +} +``` + +From there, you can use the `first` page to start getting items. For example, a `GET` request to `https://example.org/users/someone/following?limit=40` will produce something like: + +```json +{ + "@context": "https://www.w3.org/ns/activitystreams", + "id": "https://example.org/users/someone/following?limit=40", + "next": "https://example.org/users/someone/following?limit=40&max_id=01V1AY4ZJT4JK1NT271SH2WMGH", + "orderedItems": [ + "https://example.org/users/someone_else", + "https://somewhere.else.example.org/users/another_account", + [... 38 more entries here ...] + ], + "partOf": "https://example.org/users/someone/following", + "prev": "https://example.org/users/someone/following?limit=40&since_id=021HKBY346X7BPFYANPPJN493P", + "totalItems": 397, + "type": "OrderedCollectionPage" +} +``` + +You can then use the `next` and `prev` endpoints to page down and up through the OrderedCollection. + +!!! Info "Hidden Followers / Following Collections" + + GoToSocial allows users to hide their followers/following collections if they wish. + + If a user has chosen to hide their collections, then only a stub collection with `totalItems` will be returned, and you will not be able to page through the Actor's followers/following collections. + + A `GET` to the following collection of an Actor with hidden collections will look like: + + ```json + { + "@context": "https://www.w3.org/ns/activitystreams", + "id": "https://example.org/users/someone/following", + "type": "OrderedCollection", + "totalItems": 397 + } + ``` + ## Conversation Threads Due to the nature of decentralization and federation, it is practically impossible for any one server on the fediverse to be aware of every post in a given conversation thread. diff --git a/docs/user_guide/settings.md b/docs/user_guide/settings.md index 390e5c209..7bcbb762f 100644 --- a/docs/user_guide/settings.md +++ b/docs/user_guide/settings.md @@ -88,15 +88,6 @@ This option is often referred to on the fediverse as "locking" your account. After ticking or unticking the checkbox, be sure to click on the `Save profile info` button at the bottom to save your new settings. -#### Enable RSS Feed of Public Posts - -RSS feeds for users are disabled by default, but can be opted into with this checkbox. For more information see [RSS](./rss.md). - -This feed only includes posts set as 'Public' (see [Privacy Settings](./posts.md#privacy-settings)). - -!!! warning - Exposing your RSS feed allows *anyone* to subscribe to updates on your Public posts anonymously, bypassing follows and follow requests. - #### Mark Account as Discoverable by Search Engines and Directories This setting updates the 'discoverable' flag on your account. @@ -114,6 +105,21 @@ Turning on the discoverable flag may take a week or more to propagate; your acco !!! info The discoverable setting is about **discoverability of your account**, not searchability of your posts. It has nothing to do with indexing of your posts for search by Mastodon instances, or other federated instances that use full text search! +#### Enable RSS Feed of Public Posts + +RSS feeds for users are disabled by default, but can be opted into with this checkbox. For more information see [RSS](./rss.md). + +This feed only includes posts set as 'Public' (see [Privacy Settings](./posts.md#privacy-settings)). + +!!! warning + Exposing your RSS feed allows *anyone* to subscribe to updates on your Public posts anonymously, bypassing follows and follow requests. + +#### Hide Who You Follow / Are Followed By + +By default, GoToSocial shows your following/followers counts on your public web profile, and allows others to see who you follow and are followed by. This can be useful for account discovery purposes. However, for privacy + safety reasons you may wish to hide these counts, and to hide your following/followers lists from other accounts. You can do this by checking this box. + +With the box checked, your following/followers counts will be hidden from your public web profile, and others will not be able to page through your following/followers lists. + ### Advanced #### Custom CSS |