Add jobs endpoint documentation #29
Conversation
| "status": ONE OF ["pending", "success", "error"], | ||
| "jobTicket": "TICKET", | ||
| "dateCreated": "ISO 8601 DATETIME", | ||
| "userId": "Foo" |
There was a problem hiding this comment.
@archolewa This does not include dateUpdated as our job payload does not currently give dateUpdated. (It's not a part of the job payload in the design docs)
|
@cdeszaq @archolewa Please review |
|
@archolewa Added dateUpdated |
| @@ -561,6 +563,100 @@ There are, however, a few catches to this: | |||
| - Sorting is only applied at the Druid level. Therefore, the results of a sort are not guaranteed to be accurate if Fili | |||
| performs any post-Druid calculations on one of the metrics that you are sorting on. | |||
|
|
|||
| Asynchronous Queries | |||
| ---- | |||
There was a problem hiding this comment.
The --- should be the same length as the title.
|
Finished my latest pass. A bit more about the filters (a link to the data filter section will go a long way) would be nice. |
| If no jobs are available in the system, we get an empty collection. | ||
|
|
||
| The `jobs` endpoint supports the `filters` query param that filters the JobRows according to the filter condition and | ||
| only returns the JobRows that satisfy the filter condition. |
There was a problem hiding this comment.
I think I would rephrase this to make it clearer what we can filter on:
The `jobs` endpoint supports filtering on job fields (i.e. `userId`, `status`), using the same syntax as the [data endpoint filters](#filtering). For example:
userId-eq[greg, joan], status-eq[success]
resolves into the following boolean operation:
(userId = greg OR userId = joan) AND status = success
which will return only those Jobs created by `greg` and `joan` that have completed successfully.
There was a problem hiding this comment.
To add to @archolewa comments a bit: the core idea here is to tie it back to the filters that users are already familiar with, and leave the terminology centered around "jobs" since that's what they are interacting with. JobRow is an internal concept, really, so we don't want to expose that in the API if we don't have to
There was a problem hiding this comment.
Also, add a link in there back up to where we talk about filters in general
|
Made a small suggestion to hopefully make the filter documentation a bit clearer. 👍 Once that's been addressed. |
|
|
||
| 1. Providing the status of tickets queried via the `jobs/TICKET` resource. | ||
| 2. Provide a list of all jobs in the system. | ||
| 3. Providing access to the results via the `jobs/TICKET/results` resource. |
There was a problem hiding this comment.
Would be good to have these in order of coarsest to finest resource (ie. /jobs, /jobs/TICKET, and /jobs/TICKET/results)
/NotABlocker
There was a problem hiding this comment.
Could turn each of these into links into the section that talks about it below.
/NotABlocker
|
Just a couple final small things and this looks good |
|
@archolewa @cdeszaq all comments have been addressed |
| 1. Provide a list of [all jobs](#get-ting-summary-of-all-jobs) in the system. | ||
| 2. Providing the status of a [particular job](#get-ting-job-status) queried via the `jobs/TICKET` resource. | ||
| 3. Providing access to the [results](#get-ting-results) via the `jobs/TICKET/results` resource. | ||
|
|
There was a problem hiding this comment.
#1 should probably also be Providing.
|
👍 after the few final small tweaks |
cdeszaq
added
MERGEABLE
NEED CHANGES
NEED SQUASH
and removed
NEED 1 REVIEW
REVIEWABLE
labels
|
👍 Seems fine. |
venisa
force-pushed
the
Add-Jobs-endpoint-documentation
branch
from
9d0bcd1 to
7fcfbcc
Compare
venisa
force-pushed
the
Add-Jobs-endpoint-documentation
branch
from
7fcfbcc to
19873c9
Compare
cdeszaq
force-pushed
the
Add-Jobs-endpoint-documentation
branch
from
19873c9 to
c58f9e6
Compare
Add documentation for Jobs endpoint.
Please note:
I have provided a very brief description for async. However, the focus of this PR is to document the Jobs endpoint.
@cdeszaq @archolewa you guys had reviewed this when this was opened in bard.
I addressed all outstanding comments and added a new commit for filters on jobs endpoint