Add documentation on new timelines_access instance configuration attribute

[ClearlyClaire]

Fixes MAS-607

[daprice]

Thanks! As a client dev I’d appreciate if the docs could clarify how calls to timeline APIs will behave based on these settings.

For example if I make an unauthenticated call to /api/v1/timelines/tag/SomeHashtag without specifying local or remote parameters, on a server where hashtag_feeds.local is “public” and hashtag_feeds.remote is “authenticated”, will I get a 401, or will I get the timeline response with remote posts filtered out?

What if I make the same call with remote=true: should I expect 401, or an empty response? And so on.

If a feed is set to “disabled”, how can API clients determine what the “special role” is and whether the current user has it?

[ClearlyClaire]

For example if I make an unauthenticated call to /api/v1/timelines/tag/SomeHashtag without specifying local or remote parameters, on a server where hashtag_feeds.local is “public” and hashtag_feeds.remote is “authenticated”, will I get a 401, or will I get the timeline response with remote posts filtered out?

What if I make the same call with remote=true: should I expect 401, or an empty response? And so on.

For unauthenticated requests to endpoints covering that are not allowed, 401 is returned, because there is precedent for that with the previous setting to disable those feeds for unauthenticated access.

For authenticated access, this will always return a 200 ok, but results will be filtered accordingly.

[oneiros]

Excellent addition and I approve this, feel free to merge as is.

If you like, I think there is a tiny opportunity to streamline this a little: The Descriptions all start with "Information with regards to access restrictions ...". I think the "Information with regards to" part is a bit redundant and could just be removed. So for example "Information with regards to access restrictions on different timelines." would become "Access restrictions on different timelines.".

[daprice]

Perfect, thanks for the clarification!