Skip to content

Commit

Permalink
HARMONY-1577: As a user, I would like to view documentation for the /…
Browse files Browse the repository at this point in the history 
…jobs endpoints.
  • Loading branch information
@ygliuvt
ygliuvt committed Nov 22, 2023
1 parent 18a1659 commit 0fb5055
Show file tree
Hide file tree
Showing 3 changed files with 66 additions and 12 deletions.
4 changes: 2 additions & 2 deletions services/harmony/app/markdown/capabilities.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

```
Expand All @@ -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

```
Expand Down
70 changes: 62 additions & 8 deletions services/harmony/app/markdown/jobs.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
### <a name="jobs-details"></a> 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

```
Expand All @@ -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.

##### <a name="query-parameters"></a> Query Parameters
| parameter | description |
|-----------|-----------------------------|
| page | Current page number |
| limit | Number of jobs in each page |
---
**Table {{tableCounter}}** - Harmony jobs endpoint parameters

##### <a name="jobs-response"></a> 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.

```
Expand All @@ -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
##### <a name="job-response"></a> 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`.

```
Expand All @@ -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`.

```
Expand All @@ -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`.

```
Expand All @@ -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
Expand All @@ -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/<job-id>/skip-preview
Expand Down
4 changes: 2 additions & 2 deletions services/harmony/app/markdown/stac.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

```
Expand All @@ -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 `<item-index>` is the index of the STAC catalog item within the job's output STAC catalog. It starts at 0.

Expand Down

0 comments on commit 0fb5055

Please sign in to comment.