From 0fb5055c2b69fae8952af7b7dcc5b64ab981ffb7 Mon Sep 17 00:00:00 2001 From: Yonggang Liu Date: Tue, 21 Nov 2023 10:48:14 -0500 Subject: [PATCH] HARMONY-1577: As a user, I would like to view documentation for the /jobs endpoints. --- services/harmony/app/markdown/capabilities.md | 4 +- services/harmony/app/markdown/jobs.md | 70 ++++++++++++++++--- services/harmony/app/markdown/stac.md | 4 +- 3 files changed, 66 insertions(+), 12 deletions(-) diff --git a/services/harmony/app/markdown/capabilities.md b/services/harmony/app/markdown/capabilities.md index dda4f05ec..2c5fd8082 100644 --- a/services/harmony/app/markdown/capabilities.md +++ b/services/harmony/app/markdown/capabilities.md @@ -31,7 +31,7 @@ The returned JSON response will have the configured capabilities in Harmony for --- **Table {{tableCounter}}** - Harmony capabilities endpoint response fields -##### Getting Harmony capabilities for a given collection by collection concept id +#### Getting Harmony capabilities for a given collection by collection concept id ``` @@ -40,7 +40,7 @@ The returned JSON response will have the configured capabilities in Harmony for ``` **Example {{exampleCounter}}** - Getting Harmony capabilities for a given collection by collection concept id -##### Getting Harmony capabilities for a given collection by collection short name +#### Getting Harmony capabilities for a given collection by collection short name ``` diff --git a/services/harmony/app/markdown/jobs.md b/services/harmony/app/markdown/jobs.md index ad27437f2..7d8ca33ef 100644 --- a/services/harmony/app/markdown/jobs.md +++ b/services/harmony/app/markdown/jobs.md @@ -1,8 +1,10 @@ ### Monitoring Jobs with the Jobs API and the Workflow-UI -Jobs can be monitored using the `jobs` API as well as with the [Workflow-UI](/workflow-ui) web application. +Jobs can be monitored using the jobs API as well as with the [Workflow-UI](/workflow-ui) web application. -##### Getting the list of jobs for a user +There are two set of jobs API endpoints with the same sub paths and parameters: one with path `jobs` to view and control the current user's own jobs; the other with `admin/jobs` path to view and control all users' jobs if the current user has admin permission to do so. For simplicity, we will only list the ones for regular user below. + +#### Getting the list of jobs for a user ``` @@ -11,7 +13,30 @@ Jobs can be monitored using the `jobs` API as well as with the [Workflow-UI](/wo ``` **Example {{exampleCounter}}** - Getting the user's list of jobs using the `jobs` API -##### Getting job status +Returns the list of Harmony jobs submitted by the user. By default, 10 jobs are returned in the response. User can use the paging query parameters to page through the whole result set or/and change the number of jobs that will be returned in each page. + +##### Query Parameters +| parameter | description | +|-----------|-----------------------------| +| page | Current page number | +| limit | Number of jobs in each page | +--- +**Table {{tableCounter}}** - Harmony jobs endpoint parameters + +##### Response +The returned JSON response will list the total number of jobs that blong to the user, details of the jobs on the current page and links to traverse to the previous, next, first or last pages of the result set: + +| field | description | +|-------|------------------------------------------------------------------------------------------------------------------------| +| count | Total number of jobs | +| jobs | A list of JSON objects with fields describe the job in details. For details, see [job status response](#job-response). | +| links | A list of links to traverse to the previous, next, first or last pages of the result set. | +--- +**Table {{tableCounter}}** - Harmony jobs response fields + +#### Getting job status + +Get details for a given job. ``` @@ -20,7 +45,29 @@ Jobs can be monitored using the `jobs` API as well as with the [Workflow-UI](/wo ``` **Example {{exampleCounter}}** - Getting job status -##### Pausing a job +##### Response +The returned JSON response list the details of the given job: + +| field | description | +|------------------|------------------------------------------------------------------------------------------------| +| username | Username that owns the job | +| status | Status of the job | +| message | Processing message of the job | +| progress | Percentage of the job processing progress. `100` for a job that has been processed completely. | +| createdAt | Timestamp when the job was submitted to Harmony | +| updatedAt | Timestamp when the job was last updated in Harmony | +| dataExpiration | Timestamp when the result data of the job will be cleaned up from Harmony | +| links | A list of JSON objects with links to STAC catalog and result data of the job | +| request | The original request url of the job | +| numInputGranules | number of input granules in the job | +| jobID | ID of the job in Harmony | +--- +**Table {{tableCounter}}** - Harmony job response fields + + +#### Pausing a job + +User can pause a job with the following API call. The returned response is the same as the [job status response](#job-response) with the job status as `paused`. ``` @@ -29,7 +76,10 @@ Jobs can be monitored using the `jobs` API as well as with the [Workflow-UI](/wo ``` **Example {{exampleCounter}}** - Pausing a running job -##### Resuming a paused job + +#### Resuming a paused job + +User can resume a paused job with the following API call. The returned response is the same as the [job status response](#job-response) with the job status as `running`. ``` @@ -38,7 +88,10 @@ Jobs can be monitored using the `jobs` API as well as with the [Workflow-UI](/wo ``` **Example {{exampleCounter}}** - Resuming a paused job -##### Canceling a job + +#### Canceling a job + +User can cancel a job with the following API call. The returned response is the same as the [job status response](#job-response) with the job status as `canceled`. ``` @@ -47,6 +100,9 @@ Jobs can be monitored using the `jobs` API as well as with the [Workflow-UI](/wo ``` **Example {{exampleCounter}}** - Canceling a running job + +#### Skipping preview + Jobs involving many granules will by default pause automatically after the first few granules are processed. This allows the user to examine the output to make sure things look right before waiting for the entire job to complete. If things looks good, the @@ -56,8 +112,6 @@ If a user wishes to skip this step they can pass the `skipPreview` flag mentione [Services API section](#using-the-service-apis), or they can tell an already running job to skip the preview using the following: -##### Skipping preview - ``` {{root}}/jobs//skip-preview diff --git a/services/harmony/app/markdown/stac.md b/services/harmony/app/markdown/stac.md index 03ede58e0..52766831a 100644 --- a/services/harmony/app/markdown/stac.md +++ b/services/harmony/app/markdown/stac.md @@ -2,7 +2,7 @@ Harmony uses [STAC catalog](https://stacspec.org/en) to provide input and output, and communicate between services. The following endpoints provides access to the output STAC catalog and catalog items of a finished job. -##### Getting the STAC catalog of a single job +#### Getting the STAC catalog of a single job ``` @@ -11,7 +11,7 @@ Harmony uses [STAC catalog](https://stacspec.org/en) to provide input and output ``` **Example {{exampleCounter}}** - Getting the STAC catalog of a single job -##### Getting the STAC catalog item within a job's STAC catalog +#### Getting the STAC catalog item within a job's STAC catalog The `` is the index of the STAC catalog item within the job's output STAC catalog. It starts at 0.