v0.28 tasks #1746
v0.28 tasks #1746
Conversation
Also delete code sample related to removed get one task by index endpoint.
| @@ -6,99 +6,98 @@ The `/tasks` route gives information about the progress of [asynchronous operati | |||
| The task `uid` is incremented **globally.** | |||
| ::: | |||
|
|
|||
| ## Get all tasks | |||
| ## Get tasks | |||
There was a problem hiding this comment.
Would it be a good idea if we set the example headings to H4 and add sidebarDepth: 2?That way the filtering and paginating headings will be more visible
There was a problem hiding this comment.
I don't think we should do it as part of this PR because it would make it less consistent w/ the other API ref pages where the example is always an H3. But in general, I think this is a great idea.
Rationale: we don't really need examples to show up in the sidebar, but we would like people to be able to easily find other things that aren't endpoints (e.g. object definitions, special subsections like filtering or pagination above). So it would make sense to use H3s for these, and H4s for all example + query parameter + body subsections. Then set sidebarDepth to 2 for the whole API reference section.
Could you make a note about this on the API reference template PR or issue, please?
There was a problem hiding this comment.
I also like the idea of highlighting subsections that might help users, and I also agree it doesn't belong to this PR.
Something to take into account, though: HTML headings (h1 through h6) are semantic structures. As in, using an H4 after an H3 implies the H4 is a subsection of H3. I also think that not using headings sequentially (e.g. H1 followed by H3 instead of H1 followed by H2) can mess up the document outline.
What I'm trying to say is: we should avoid as much as possible using a specific heading only because of the effect this will have on the sidebar. AFAIK, this is particularly relevant when it comes to accessibility because screen readers rely on the document outline to help visually impaired users navigate a page. If we find ourselves willingly using tags erroneously, it's an indication we need to update our website/tooling/etc.
There was a problem hiding this comment.
That's very interesting Gui, thanks for bringing it up. Not that this is particularly relevant, but we already do a lot of this: using non-sequential heading levels not for their effect on the sidebar, but for their visual effect on the page. See: most "query parameters" or "body" sections in the API references (H4s belonging to parent H2s).
There was a problem hiding this comment.
Added a few comments to the files themselves. Mostly minor stuff and questions.
Also, I noticed that most of the new code samples on /reference/api/tasks.md are in code blocks instead of the code sample component. That's for ease of review, correct?
Finally, I would encourage requesting a review from a core team member.
|
|
||
| <RouteHighlighter method="GET" route="/tasks"/> | ||
|
|
||
| List all tasks globally, regardless of index. The `task` objects are contained in the `results` array. | ||
|
|
||
| Tasks are always returned in descending order of `uid`. This means that by default, **the most recently created `task` objects appear first**. |
There was a problem hiding this comment.
Should this be uid or taskUid?
There was a problem hiding this comment.
It should be uid. taskUid is only used in the summarized task object returned from async endpoints. Confusing, I know 🙁
Co-authored-by: gui machiavelli <[email protected]>
Also rename get_all_tasks_by_index_1
|
bors merge |
|
Build succeeded: |
Changes related to the tasks API in v0.28. For a description of these changes, see the associated issue.