API docs for user preferences #1259
Conversation
|
I feel like this shouldn't be a top level section of the Central API, but should be nested under the Accounts and Users section, probably after You could also mention this in the 2024.3 section of the changelog. There is already one bullet point there. |
I thought about that at the time but thought it'd be better to follow the URL scheme. But yeah, the rest of the documentation doesn't do that always either. Fixed in e6a236e!
What stopped me at the time was the Changelog subscript that says "Here major and breaking changes to the API are listed by version"; I didn't consider this API addition as major. Do you feel it's major? |
There was a problem hiding this comment.
I have a few more minor requests but you can make those changes and go ahead and merge!
Do you feel it's major?
I think so! I mean, it's a whole new set of endpoints... now that the doors of a few user preferences have been opened, folks (like the QA team) are already starting to ask for more!
Even if it's targeted at ourselves, it would be useful to note it. I can see myself glancing through the changelog to remind myself when user preferences were added to the API.
| - name: Authorization | ||
| in: header | ||
| description: Bearer encoding of a token of the user whose preferences to operate on | ||
| required: true | ||
| schema: | ||
| type: string | ||
| example: Bearer lSpAIeksRu1CNZs7!qjAot2T17dPzkrw9B4iTtpj7OoIJBmXvnHM8z8Ka4QPEjR7 |
There was a problem hiding this comment.
This auth header doesn't need to be included in these example requests... (it's not in any of the other examples)
| If you _do_ use `current`, you may request extended metadata. Supply an `X-Extended-Metadata` header value of `true` to additionally retrieve an array of strings of the `verbs` the authenticated User/Actor is allowed to perform server-wide. | ||
| If you _do_ use `current`, you may request extended metadata. Supply an `X-Extended-Metadata` header value of `true` to additionally receive: | ||
| — an array of strings of the `verbs` the authenticated User/Actor is allowed to perform server-wide | ||
| — an object containing the preferences of the authenticated User/Actor |
There was a problem hiding this comment.
Could you add an example of this to the example extended response below?
Also the formatting of this list is not looking as pretty as you might think:
| - name: User Preferences | ||
| x-parent-tag: Accounts and Users | ||
| description: |- | ||
| The Central frontend uses this API to save various user preferences, such as the sorting order of certain listings. When a user starts a new session, these preferences are loaded in. |
There was a problem hiding this comment.
Could you add a short sentence or statement to link to this other part of the API? I think that would make it clearer where these users preferences are later gotten from:
[link text](/central-api-accounts-and-users/#getting-authenticated-user-details)
Towards #1211
I've hauled it through the sphinx circus to make sure it gets rendered.