diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build.yml similarity index 51% rename from .github/workflows/build-docs.yml rename to .github/workflows/build.yml index 4470ba4..3b0feae 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build.yml @@ -1,26 +1,30 @@ name: Build OpenAPI docs -on: - - push - # - pull_request +on: + push: + branches: + - main + - develop + - 'release*' + pull_request: + types: [opened, reopened, sychronize] jobs: docs-build: runs-on: ubuntu-latest - # env: - # TRAVIS_BRANCH: ${{ github.event.number }} - # a trick that builds docs for PRs (with PR number). Does not work for PRs from forks. steps: - name: Setup Node.js environment - uses: actions/setup-node@v2.5.1 - with: + uses: actions/setup-node@v4 + with: node-version: 14.x # Comes with npm 6. For newer Node, encountered: https://github.com/npm/cli/issues/3359 - run: npm install -g @redocly/openapi-cli && npm install -g redoc-cli - run: npm install -g gh-openapi-docs - name: Check out repository code - uses: actions/checkout@v2 + uses: actions/checkout@v4 - run: gh-openapi-docs - name: Deploy 🚀 - uses: JamesIves/github-pages-deploy-action@v4.2.2 + uses: JamesIves/github-pages-deploy-action@v4 with: branch: gh-pages folder: . + target-folder: ${{ github.ref == 'refs/heads/main' && 'docs/index.html' || '' }} # Deploy to docs/index.html only if on main + clean: ${{ github.ref == 'refs/heads/main' }} # Clean only if on the main branch diff --git a/.github/workflows/lint-validate-openapi.yml b/.github/workflows/ci.yml similarity index 73% rename from .github/workflows/lint-validate-openapi.yml rename to .github/workflows/ci.yml index 16a00a8..e12d7da 100644 --- a/.github/workflows/lint-validate-openapi.yml +++ b/.github/workflows/ci.yml @@ -1,37 +1,31 @@ name: Lint and validate OpenAPI specs - on: - - push - pull_request - jobs: - lint: name: Lint OpenAPI definition runs-on: ubuntu-latest steps: - name: Check out head branch - uses: actions/checkout@v2 + uses: actions/checkout@v4 - name: Run OpenAPI Lint Action - uses: nwestfall/openapi-action@v1.0.2 + uses: mhiew/redoc-lint-github-action@v4 with: - github_token: ${{ secrets.GITHUB_TOKEN }} - file: openapi/task_execution_service.openapi.yaml - + args: 'openapi/task_execution_service.openapi.yaml' diff: name: Show OpenAPI differences relative to target branch runs-on: ubuntu-latest if: ${{ github.event_name == 'pull_request' }} steps: - name: Check out head branch - uses: actions/checkout@v2 + uses: actions/checkout@v4 with: - ref: ${{ github.head_ref }} + ref: ${{ github.ref }} path: head - name: Check out base branch - uses: actions/checkout@v2 + uses: actions/checkout@v4 with: - ref: ${{ github.base_ref }} + ref: ${{ github.event.pull_request.base.ref }} path: base - name: Run OpenAPI Diff Action uses: mvegter/openapi-diff-action@v0.23.5 @@ -44,7 +38,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Check out head branch - uses: actions/checkout@v2 + uses: actions/checkout@v4 - name: Run OpenAPI Validate Action uses: char0n/swagger-editor-validate@v1 with: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b90a8fd..247786b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,34 +1,47 @@ # CONTRIBUTING -This schema is developed by the [Cloud Work Stream](https://ga4gh.cloud) of the [Global Alliance for Genomics and Health](https://ga4gh.org). +This schema is developed by the [Cloud Work +Stream]([https://ga4gh.cloud](https://www.ga4gh.org/work_stream/cloud/)) of the +[Global Alliance for Genomics and Health](https://ga4gh.org). ## Semantic Versioning -We use [semantic versioning](https://semver.org/) for TES, this will determine if your proposed changes impact a major or minor release. +The Task Execution Service (TES) API uses [semantic +versioning](https://semver.org/) for TES. Please consider that breaking changes +imply a new major version release, which is associated with considerable +administrative work and therefore happen only rarely. ## Suggesting Changes -Suggested changes to this schema can be initiated as [**Issues**](https://github.com/ga4gh/task-execution-schemas/issues) or [**Pull Requests**](https://github.com/ga4gh/task-execution-schemas/pulls) to allow for discussion and review. - -Even those with write access to the main repository should in general create pull request branches within their own forks. This way when the main repository is forked again, the new fork is created with a minimum of extraneous volatile branches. - -> To facilitate review of external pull requests, users are encouraged to activate [**Travis CI**](https://travis-ci.org/) to monitor the build status (documentation, Swagger UI) of their fork. By following the documentation for [deployment to GitHub Pages](https://docs.travis-ci.com/user/deployment/pages/) and adding a `$GITHUB_TOKEN` environment variable to their repo configuration, pushes to the forked repo should be viewable relative to `https://[user-or-org].github.io/workflow-execution-service-schemas/preview//`: - -+ https://[user-or-org].github.io/task-execution-schemas/preview/\/docs/ -+ https://[user-or-org].github.io/task-execution-schemas/preview/\/swagger-ui/ -+ https://[user-or-org].github.io/task-execution-schemas/preview/\/swagger.json -+ https://[user-or-org].github.io/task-execution-schemas/preview/\/swagger.yaml - -> Providing this base URL in the pull request comment is appreciated, but not required. - -If a security vulnerability is identified with the specification please send an email to security-notification@ga4gh.org detailing your concerns. - -## Approving Changes - -### pre-TES v1.0.0 / Testbed Voting Procedure -Changes for the release are to be approved by 2 TES specification leads. - -### post TES v1.0.0 Voting Procedure -The post v1.0.0 voting group include stakeholders, such as server and client implementors. -The membership of this group will be established as part of the v1.0.0 release. +Changes to TES can be initiated as +[**issues**](https://github.com/ga4gh/task-execution-schemas/issues) or +[**pull requests**](https://github.com/ga4gh/task-execution-schemas/pulls) to +allow for discussion and review. For considerable changes, we generally +recommend opening issues first in order to discuss scope and feasibility. + +When creating pull requests, please do so from your own fork - even if you have +write access to the repository. In this way, when the main repository is forked +again, the new fork is created with a minimum of extraneous, volatile branches. + +> To facilitate the review of external pull requests, users are encouraged to +> activate [**GitHub Actions**](https://github.com/features/actions) to monitor +> the build status of their fork. By following the documentation for [deployment +> to GitHub +> Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site), +> pushes to the forked repository will be viewable at +> `https://[user-or-org].github.io/task-execution-service/preview//`, +> e.g.,: +> - `https://[user-or-org].github.io/task-execution-schemas/preview/\/docs/` +> - `https://[user-or-org].github.io/task-execution-schemas/preview/\/swagger-ui/` +> - `https://[user-or-org].github.io/task-execution-schemas/preview/\/swagger.json` +> - `https://[user-or-org].github.io/task-execution-schemas/preview/\/swagger.yaml` + +Providing this base URL in the pull request comment is appreciated, but not +required. + +If a security vulnerability is identified with the specification, please send an +email to detailing your concerns. + +For more information please refer to the [**governance +documentation**](GOVERNANCE.md). diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000..b51aba6 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,19 @@ +TES Governance and Process +============================== + +The Task Execution Service (TES) operates under a community-driven development model, where advancements to the specification occur exclusively through community contributions. The standard is governed by a core team of Product Leads that fosters collaboration and consensus among contributors. This team is tasked with overseeing the design and development processes, setting priorities, managing the release schedule, and making decisions in instances where consensus cannot be reached. + +Current TES Product Leads are: + +| Name | Organization | github | +|:-------------------|:-------------|:------------------ +| Kyle Ellrot | [Oregon Health and Science University](https://www.ohsu.edu/) | [kellrott](https://github.com/kellrott) | +| Venkat Malladi | [Microsoft](https://www.microsoft.com/en-us/genomics/) | [vsmalladi](https://github.com/vsmalladi) | +| Alex Kanitz | [Swiss Institute of Bioinformatics / ELIXIR Switzerland](https://www.sib.swiss/) | [uniqueg](https://github.com/uniqueg) | + + +## Voting Procedure + +Proposed changes and releases are voted on by Driver Project champions and other key stakeholders, such as product implementers (client- and sever-side). Product Leads review proposed changes on a regular product-specific call, then solicit community feedback during regular Cloud Work Stream calls and through the [product-specific](mailto:ga4gh-cloud-tes+subscribe@ga4gh.org) mailing list for a specified time period. Proposed releases are further shared through official GA4GH channels (Slack board and mailing list with wider scope) and with a longer feedback period. Product Leads, in close connection with the Cloud Work Stream leadership, will always strive to reach broad consensus, but may accept simple majority decisions if broad consensus cannot be reached. + +Sign up for the [**GA4GH TES API mailing list**](mailto:ga4gh-cloud-tes+subscribe@ga4gh.org) to stay updated about the latest news and developments around the TES API, in particular for soliciting comments on proposed specification changes and for notifications about TES subgroup meetings. diff --git a/README.md b/README.md index 1ae91c4..6103d6e 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,73 @@ -GA4GH Logo +GA4GH Logo + +[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0) +[![release_badge](https://img.shields.io/github/v/tag/ga4gh/task-execution-schemas?label=latest%20release&logo=github&style=flat)](https://github.com/ga4gh/task-execution-schemas/releases) + +| Branch | CI Docs | CI Specs | Swagger Validator | +|---|---|---|---| +| `main` | [![Build Status](https://github.com/ga4gh/task-execution-schemas/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/ga4gh/task-execution-schemas/actions/workflows/build.yml?query=branch%3Amain) | [![CI Status](https://github.com/ga4gh/task-execution-schemas/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ga4gh/task-execution-schemas/actions/workflows/ci.yml?query=branch%3Amain) | [![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fga4gh%2Ftask-execution-schemas%2Fmain%2Fopenapi%2Ftask_execution_service.openapi.yaml&label=OpenAPI)](https://editor.swagger.io/?url=https://raw.githubusercontent.com/ga4gh/task-execution-schemas/refs/heads/main/openapi/task_execution_service.openapi.yaml) | +| `develop` | [![Build Status](https://github.com/ga4gh/task-execution-schemas/actions/workflows/build.yml/badge.svg?branch=develop)](https://github.com/ga4gh/task-execution-schemas/actions/workflows/build.yml?query=branch%3Adevelop) | [![CI Status](https://github.com/ga4gh/task-execution-schemas/actions/workflows/ci.yml/badge.svg?branch=develop)](https://github.com/ga4gh/task-execution-schemas/actions/workflows/ci.yml?query=branch%3Adevelop) | [![Swagger Validator](https://img.shields.io/swagger/valid/3.0?specUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fga4gh%2Ftask-execution-schemas%2Fdevelop%2Fopenapi%2Ftask_execution_service.openapi.yaml&label=OpenAPI)](https://editor.swagger.io/?url=https://raw.githubusercontent.com/ga4gh/task-execution-schemas/refs/heads/develop/openapi/task_execution_service.openapi.yaml) | Task Execution Service (TES) API -====================================== -`master` branch status: [![Build Status](https://travis-ci.org/ga4gh/task-execution-schemas.svg?branch=master)](https://travis-ci.org/ga4gh/task-execution-schemas?branch=master) -Open API Validator +================================ -The [Global Alliance for Genomics and Health](http://genomicsandhealth.org/) is an international coalition, formed to enable the sharing of genomic and clinical data. +This repository is the home for the schema of the Task Execution Service (TES) +API defined by the[Cloud Work Stream](https://www.ga4gh.org/work_stream/cloud/) +of the [Global Alliance for Genomics and Health (GA4GH)](https://ga4gh.org/). +The goal of the API standard is to provide a uniform way to executing batch +computing tasks. -Cloud Work Stream ------------------ +[GA4GH](https://ga4gh.org/) is an international coalition, formed to enable the +sharing and processing of genomic data. -The [Cloud Work Stream](https://ga4gh.cloud) helps the genomics and health communities take full advantage of modern cloud environments. -Our initial focus is on “bringing the algorithms to the data”, by creating standards for defining, sharing, and executing portable workflows. +The [Cloud Work Stream](https://www.ga4gh.org/work_stream/cloud/) helps the +genomics and health communities take full advantage of modern cloud +environments. Our initial focus is on “bringing the algorithms to the data”, by +creating standards for defining, sharing, and executing portable workflows. -We work with platform development partners and industry leaders to develop standards that will facilitate interoperability. +We work with platform development partners and industry leaders to develop +standards that will facilitate interoperability. What is TES? ============ -The Task Execution Service (TES) API is an effort to define a standardized schema -and API for describing batch execution tasks. A task defines a set of input files, -a set of (Docker) containers and commands to run, a set of output files, -and some other logging and metadata. +The Task Execution Service (TES) API is an effort to define a standardized +schema and API for describing batch execution tasks. A task defines a set of +commands to run, a set of (Docker) containers to run them _in_, sets of input +and output files, required resources, as well as some other metadata, e.g., for +capturing provenance information. API Definition -------------- -See the human-readable [Reference Documentation](https://ga4gh.github.io/task-execution-schemas/docs/) -and the [OpenAPI YAML description](openapi/task_execution_service.openapi.yaml). You can also explore the specification in the [Swagger Editor](https://editor.swagger.io/?url=https://ga4gh.github.io/task-execution-schemas/openapi.yaml). +See the human-readable [**reference +documentation**](https://ga4gh.github.io/task-execution-schemas/docs/). + +> The documentation hosted at +> reflects the latest official API release from the `main` branch. To explore +> the documentation from a development branch, append +> `preview//docs/` to the base URL. For example, to view the +> documentation for the latest **development version of the specification**, +> visit . -> All documentation and pages hosted at 'ga4gh.github.io/task-execution-schemas' reflect the latest API release from the `master` branch. To monitor the latest development work, add 'preview/\' to the URLs above (e.g., 'ga4gh.github.io/task-execution-schemas/preview/\/docs'). +You can also examine the specification in the [**Swagger +Editor**](https://editor.swagger.io/?url=https://raw.githubusercontent.com/ga4gh/task-execution-schemas/refs/heads/main/openapi/task_execution_service.openapi.yaml). + +> If you want to explore a version from a development branch, please load the +> corresponding specification file (in +> `openapi/task_execution_service.openapi.yaml`) manually into the [Swagger +> Editor](https://editor.swagger.io/). TES Compliant Implementations ------------------------------- +----------------------------- -> A stand-alone security review has been performed on the API. Nevertheless, any implementation that is linked to from the documentation accompanying the API is done so without any security guarantees. If you integrate this code into your application it is AT YOUR OWN RISK AND RESPONSIBILITY to arrange for an audit to ensure compliance with any applicable regulatory and security requirements, especially where personal data may be at issue. +In alignment with GA4GH policies and regulations, security reviews are conducted +for each major version release of the API. However, **no security guarantees are +provided for any implementation of the API, including those linked from this +page or the associated documentation**. Users are advised to proceed at their +own risk and should arrange for a security audit of their application to ensure +compliance with relevant regulatory and security standards, particularly when +handling personal data. ### Client - [cwl-tes](https://github.com/ohsu-comp-bio/cwl-tes) @@ -46,8 +79,6 @@ TES Compliant Implementations - [Toil](https://toil.readthedocs.io/en/latest/) - [St. Jude Rust Labs](https://github.com/stjude-rust-labs/tes) - - ### Server - [Funnel](https://ohsu-comp-bio.github.io/funnel/) - [TESK](https://github.com/EMBL-EBI-TSI/TESK) @@ -57,7 +88,9 @@ TES Compliant Implementations ### Compatibility Matrix -> Compatibility is assumed based on available documentation and limited tests performed on latest versions of implementations available as of December 2020. +> Compatibility is assumed based on available documentation and limited tests +> performed on latest versions of implementations available in December 2020. +> Information may be outdated. | | cwl-tes | Cromwell | Nextflow | | ----------- | ------------- | --------- | ---------| @@ -67,58 +100,66 @@ TES Compliant Implementations TES Service Examples ------------------------------- - -The schema and APIs is defined [here](openapi/task_execution_service.openapi.yaml) in [Open Api Specification 3.0.1](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md). Clients may use JSON and REST to communicate -with a service implementing the TES API. +-------------------- +The API specification is available +[here](openapi/task_execution_service.openapi.yaml) in [OpenAPI +v3.0.1](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md). +Clients may use JSON and REST to communicate with a service implementing the TES +API. -### Create a task - +### Creating a task Here's an example of a complete task message, defining a task which calculates an MD5 checksum on an input file and uploads the output: + ```JSON { - "name": "MD5 example", - "description": "Task which runs md5sum on the input file.", - "tags": { + "name": "MD5 example", + "description": "Task which runs md5sum on the input file.", + "tags": { "custom-tag": "tag-value" - }, - "inputs": [ + }, + "inputs": [ { - "name": "infile", - "description": "md5sum input file", - "url": "/path/to/input_file", - "path": "/container/input", - "type": "FILE" + "name": "infile", + "description": "md5sum input file", + "url": "/path/to/input_file", + "path": "/container/input", + "type": "FILE" } - ], - "outputs" : [ + ], + "outputs": [ { - "url" : "/path/to/output_file", - "path" : "/container/output" + "name": "outfile", + "url": "/path/to/output_file", + "path": "/container/output" } - ], - "resources" : { + ], + "resources": { "cpuCores": 1, - "ramGb": 1.0, - "diskGb": 100.0, + "ramGb": 1, + "diskGb": 100, "preemptible": false - }, - "executors" : [ + }, + "executors": [ { - "image" : "ubuntu", - "command" : ["md5sum", "/container/input"], - "stdout" : "/container/output", - "stderr" : "/container/stderr", - "workdir": "/tmp" + "image": "ubuntu", + "command": [ + "md5sum", + "/container/input" + ], + "stdout": "/container/output", + "stderr": "/container/stderr", + "workdir": "/tmp" } - ] + ] } ``` -A minimal version of the same task, including only the required fields looks like: +A minimal version of the same task, including only the required fields looks +like: + ```JSON { "inputs": [ @@ -143,84 +184,243 @@ A minimal version of the same task, including only the required fields looks lik } ``` -To create the task, send an HTTP POST request: -```HTTP -POST /v1/tasks +To create the task, send an HTTP `POST` request to the `/tasks` endpoint: -{ "id": "task-1234" } +```HTTP +POST /ga4gh/tes/v1/tasks ``` -The return value is a task ID. +The response indicates an identifier for the created task resource: +```JSON +{ + "id": "task-1234" +} +``` -### Get a task - +### Fetching a task -To get a task by ID: +To get a task by its identifier, send an HTTP `GET` request to the `/tasks/{id}` +endpoint: ```HTTP -GET /v1/tasks/task-1234 - -{ "id": "task-1234", "state": "RUNNING" } +GET /ga4gh/tes/v1/tasks/task-1234 ``` -The return value will be a minimal description of the task state. +The default minimal response will include the task state: -To get more information, you can change the task view using the `view` URL query parameter. +```JSON +{ + "id": "task-1234", + "state": "RUNNING" +} +``` -The `basic` view will include all task fields except a few which might be -large strings (stdout/err/system logging, input parameter contents). +To get more information, you can change the task view using the `view` URL query +parameter. + +The `BASIC` view will include all task fields except a few which might be large +strings (stdout/stderr, system logging, input parameter contents): ```HTTP -GET /v1/tasks/task-1234?view=BASIC +GET /ga4gh/tes/v1/tasks/task-1234?view=BASIC +``` -{ "id": "task-1234", "state": "RUNNING", "name": "MD5 example", etc... } +```JSON +{ + "id": "task123", + "name": "Sample Task", + "description": "This is a sample task description.", + "state": "COMPLETED", + "inputs": [ + { + "name": "infile", + "description": "Input file for the task.", + "url": "/path/to/input_file", + "path": "/container/input", + "type": "FILE" + } + ], + "outputs": [ + { + "name": "outfile", + "url": "/path/to/output_file", + "path": "/container/output" + } + ], + "resources": { + "cpuCores": 1, + "ramGb": 2.0, + "diskGb": 10.0, + "preemptible": false + }, + "executors": [ + { + "image": "ubuntu:latest", + "command": ["command", "arg1", "arg2"], + "stdout": "/container/output", + "stderr": "/container/stderr", + "workdir": "/tmp" + } + ], + "created": "2024-10-24T12:00:00Z", + "updated": "2024-10-24T12:30:00Z" +} ``` -The `full` view includes stdout/err/system logs and full input parameters: +The `FULL` view includes stdout/stderr, system logs and full input parameters: ```HTTP -GET /v1/tasks/task-1234?view=FULL - -{ "id": "task-1234", "state": "RUNNING", "name": "MD5 example", - "logs": [{ "stdout": "stdout content..." }], etc... } +GET /ga4gh/tes/v1/tasks/task-1234?view=FULL ``` -### List tasks +```JSON +{ + "id": "job-0012345", + "state": "COMPLETE", + "name": "MD5 Checksum Task", + "description": "This task computes the MD5 checksum of the input file.", + "inputs": [ + { + "url": "s3://my-object-store/file1", + "path": "/data/file1" + } + ], + "outputs": [ + { + "path": "/data/outfile", + "url": "s3://my-object-store/outfile-1", + "type": "FILE" + } + ], + "resources": { + "cpu_cores": 4, + "preemptible": false, + "ram_gb": 8, + "disk_gb": 40, + "zones": "us-west-1", + "backend_parameters": { + "VmSize": "Standard_D64_v3" + }, + "backend_parameters_strict": false + }, + "executors": [ + { + "image": "ubuntu:20.04", + "command": [ + "/bin/md5", + "/data/file1" + ], + "workdir": "/data/", + "stdin": "/data/file1", + "stdout": "/tmp/stdout.log", + "stderr": "/tmp/stderr.log", + "ignore_error": true + } + ], + "volumes": [ + "/vol/A/" + ], + "tags": { + "WORKFLOW_ID": "cwl-01234", + "PROJECT_GROUP": "alice-lab" + }, + "logs": [ + { + "logs": [ + { + "start_time": "2020-10-02T10:00:00-05:00", + "end_time": "2020-10-02T11:00:00-05:00", + "stdout": "MD5 checksum calculation completed successfully.", + "stderr": "", + "exit_code": 0 + } + ], + "metadata": { + "host": "worker-001", + "slurmm_id": 123456 + }, + "start_time": "2020-10-02T10:00:00-05:00", + "end_time": "2020-10-02T11:00:00-05:00", + "outputs": [ + { + "url": "s3://my-object-store/outfile-1", + "path": "/data/outfile", + "size_bytes": 1024 + } + ], + "system_logs": [ + "Task executed successfully without any issues." + ] + } + ], + "creation_time": "2020-10-02T10:00:00-05:00" +} +``` +### Listing tasks -To list tasks: +To list all available tasks, send an HTTP `GET` requests to the `/tasks` +endpoint: ```HTTP -GET /v1/tasks +GET /ga4gh/tes/v1/tasks +``` -{ "tasks": [{ "id": "task-1234", "state": "RUNNING"}, etc...] } +```JSON +{ + "tasks": [ + { + "id": "job-0012345", + "state": "COMPLETE" + }, + { + "id": "job-0012346", + "state": "RUNNING" + }, + { + "id": "job-0012347", + "state": "FAILED" + } + ] +} ``` Similar to getting a task by ID, you may change the task view: + ```HTTP -GET /v1/tasks?view=BASIC +GET /ga4gh/tes/v1/tasks?view=BASIC ``` +### Cancelling a task -### Cancel a task +To cancel a task, send an HTTP `POST` request to the `tasks/{id}:cancel` +endpoint: - -To cancel a task, send an HTTP POST to the cancel endpoint: ```HTTP -POST /v1/tasks/task-1234:cancel +POST /ga4gh/tes/v1/tasks/task-1234:cancel ``` -Possible Future Enhancements ----------------------------- +How to Contribute Changes +------------------------- + +### Community Contributions and Spec Advancement -* Integrate with GA4GH DRS to resolve input data source (possibly support for DRS URIs as permissible values of input URLs). -* Integrate with GA4GH TRS to resolve container images (possibly support for TRS URIs as permissible values of executor image names). +The advancement of the GA4GH Task Execution Service (TES) API relies on active +community engagement and contributions. While submitting issues is an effective +way to report bugs or foster discussions about existing or proposed features, it +is important to note that these actions alone typically do not lead to +modifications in the specification. **The most effective method for implementing +changes is through the submission of a pull request (PR).** +For detailed guidance on how to contribute, please refer to the +[**contributing documentation**](CONTRIBUTING.md). -How to Contribute Changes -------------------------- +If a security issue is identified with the specification, please send an email to + detailing your concerns. -See [CONTRIBUTING.md](CONTRIBUTING.md). +### Governance -If a security issue is identified with the specification, please send an email to security-notification@ga4gh.org detailing your concerns. +The development of the TES specification is entirely community driven. However, +development is overseen by a governance committee. For more information please +refer to the [**governance documentation**](GOVERNANCE.md). diff --git a/openapi/task_execution_service.openapi.yaml b/openapi/task_execution_service.openapi.yaml index 8cf520c..fd91578 100644 --- a/openapi/task_execution_service.openapi.yaml +++ b/openapi/task_execution_service.openapi.yaml @@ -3,7 +3,7 @@ info: title: Task Execution Service version: 1.1.0 x-logo: - url: 'https://w3id.org/ga4gh/ga4gh-logo.svg' + url: 'https://www.ga4gh.org/wp-content/themes/ga4gh/dist/assets/svg/logos/logo-full-color.svg' license: name: Apache 2.0 url: 'https://raw.githubusercontent.com/ga4gh/task-execution-schemas/develop/LICENSE' @@ -63,6 +63,10 @@ info: If TES API implementation is to be used by another website or domain it must implement Cross Origin Resource Sharing (CORS). Please refer to https://w3id.org/ga4gh/product-approval-support/cors for more information about GA4GH’s recommendations and how to implement CORS. +security: + # Optionally, this section can be removed or adjusted by implementers based on their needs. + - BearerAuth: [] # Apply globally if authentication is required + - BasicAuth: [] # Alternatively, use Basic Authentication servers: - url: /ga4gh/tes/v1 @@ -85,6 +89,9 @@ paths: application/json: schema: $ref: '#/components/schemas/tesServiceInfo' + security: + - BearerAuth: [] # Endpoint secured with Bearer token + - BasicAuth: [] # Alternatively, secured with Basic Auth /tasks: get: tags: @@ -179,6 +186,11 @@ paths: application/json: schema: $ref: '#/components/schemas/tesListTasksResponse' + + security: + - BearerAuth: [] # Endpoint secured with Bearer token + - BasicAuth: [] # Alternatively, secured with Basic Auth + post: tags: - TaskService @@ -201,6 +213,9 @@ paths: schema: $ref: '#/components/schemas/tesCreateTaskResponse' x-codegen-request-body-name: body + security: + - BearerAuth: [] # Endpoint secured with Bearer token + - BasicAuth: [] # Alternatively, secured with Basic Auth /tasks/{id}: get: tags: @@ -224,6 +239,9 @@ paths: application/json: schema: $ref: '#/components/schemas/tesTask' + security: + - BearerAuth: [] # Endpoint secured with Bearer token + - BasicAuth: [] # Alternatively, secured with Basic Auth /tasks/{id}:cancel: post: tags: @@ -245,7 +263,20 @@ paths: application/json: schema: $ref: '#/components/schemas/tesCancelTaskResponse' + security: + - BearerAuth: [] # Endpoint secured with Bearer token + - BasicAuth: [] # Alternatively, secured with Basic Auth components: + securitySchemes: + BearerAuth: + type: http + scheme: bearer + bearerFormat: JWT # optional, can specify format if using JWT tokens + + BasicAuth: + type: http + scheme: basic + parameters: view: name: view @@ -579,10 +610,10 @@ components: type: object properties: cpu_cores: - type: integer - description: Requested number of CPUs - format: int32 - example: 4 + type: number + description: Requested number of CPUs. MAY be a fractional value to indicate to a scheduling algorithm that one core can be allocated to multiple jobs. For example, a value of 0.25 indicates that up to 4 jobs may run in parallel on 1 core. A value of 1.25 means that up to 3 jobs can run on a 4 core system (4/1.25 ≈ 3). Processes sharing a core MUST have the same level of isolation (typically a container or VM) that they would normally have. Scheduling systems MAY allocate fractional CPU resources by setting quotas or scheduling weights. Scheduling systems that do not support fractional CPUs MAY round up the request to the next whole number. + format: double + example: 4.25 preemptible: type: boolean description: |- @@ -593,14 +624,19 @@ components: example: false ram_gb: type: number - description: Requested RAM required in gigabytes (GB) - format: double - example: 8 + description: |- + Requested RAM required in gigabytes (GB) + (maybe fractional, but actual requested memory should + be rounded up to the next whole number of bytes) + format: float + example: 8.2 disk_gb: type: number - description: Requested disk size in gigabytes (GB) - format: double - example: 40 + description: |- + Requested disk size in gigabytes (GB) + (maybe fractional, but actual request disk should be rounded up) + format: float + example: 40.5 zones: type: array description: |-