diff --git a/requirements.txt b/requirements.txt index b7d00c8..22d4b5c 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,2 +1,2 @@ -foca==0.12.0 -gunicorn>=20.1.0,<21 \ No newline at end of file +foca==0.12.1 +gunicorn>=20.1.0,<21 diff --git a/tests/integration_tests.py b/tests/integration_tests.py index 91ecea5..1995aa6 100644 --- a/tests/integration_tests.py +++ b/tests/integration_tests.py @@ -91,7 +91,7 @@ def test_get_tools_with_params_success(): "id": "", "alias": "", "toolClass": "", - "descriptorType": "", + "descriptorType": "CWL", "registry": "", "organization": "", "name": "", diff --git a/tests/test_version.py b/tests/test_version.py new file mode 100644 index 0000000..e3b63aa --- /dev/null +++ b/tests/test_version.py @@ -0,0 +1,3 @@ +"""Tests for `version.py` module.""" + +from trs_filer.version import __version__ # noqa: F401 diff --git a/trs_filer/api/20230406.1dd4bf8.openapi.yaml b/trs_filer/api/20230406.1dd4bf8.openapi.yaml new file mode 100644 index 0000000..22c8ddb --- /dev/null +++ b/trs_filer/api/20230406.1dd4bf8.openapi.yaml @@ -0,0 +1,818 @@ +openapi: 3.0.0 +info: + title: GA4GH Tool Discovery API + description: Proposed API for GA4GH (Global Alliance for Genomics & Health) tool + repositories. A tool consists of a set of container images that are paired + with a set of documents. Examples of documents include CWL (Common Workflow + Language), WDL (Workflow Description Language), NFL (Nextflow), GXFORMAT2 + (Galaxy) or SMK (Snakemake) that describe how to use those images and a set + of specifications for those images (examples are Dockerfiles or Singularity + recipes) that describe how to reproduce those images in the future. We use + the following terminology, a "container image" describes a container as + stored at rest on a filesystem, a "tool" describes one of the triples as + described above. In practice, examples of "tools" include CWL + CommandLineTools, CWL Workflows, WDL workflows, and Nextflow workflows that + reference containers in formats such as Docker or Singularity. + version: 2.1.0 +tags: + - name: GA4GH + description: A group of web resources proposed as a common standard for tool + repositories + externalDocs: + url: https://ga4gh.github.io/tool-registry-service-schemas/ +paths: + # /service-info: + # $ref: https://raw.githubusercontent.com/ga4gh-discovery/ga4gh-service-info/v1.0.0/service-info.yaml#/paths/~1service-info + "/tools/{id}": + get: + summary: List one specific tool, acts as an anchor for self references + operationId: toolsIdGet + description: This endpoint returns one specific tool (which has ToolVersions + nested inside it). + tags: + - GA4GH + parameters: + - $ref: "#/components/parameters/id" + responses: + "200": + description: A tool. + content: + application/json: + schema: + $ref: "#/components/schemas/Tool" + "404": + description: The tool can not be found. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + # security: + # - BEARER: [] + "/tools/{id}/versions": + get: + summary: List versions of a tool + operationId: toolsIdVersionsGet + description: Returns all versions of the specified tool. + tags: + - GA4GH + parameters: + - $ref: "#/components/parameters/id" + responses: + "200": + description: An array of tool versions. + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ToolVersion" + # security: + # - BEARER: [] + "/tools/{id}/versions/{version_id}": + get: + summary: List one specific tool version, acts as an anchor for self references + operationId: toolsIdVersionsVersionIdGet + description: This endpoint returns one specific tool version. + tags: + - GA4GH + parameters: + - $ref: "#/components/parameters/id" + - $ref: "#/components/parameters/version_id" + responses: + "200": + description: A tool version. + content: + application/json: + schema: + $ref: "#/components/schemas/ToolVersion" + "404": + description: The tool can not be found. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + # security: + # - BEARER: [] + /tools: + get: + summary: List all tools + operationId: toolsGet + description: > + This endpoint returns all tools available or a filtered subset using + metadata query parameters. + tags: + - GA4GH + parameters: + - name: id + in: query + description: A unique identifier of the tool, scoped to this registry, for + example `123456`. + schema: + type: string + - name: alias + in: query + description: >- + Support for this parameter is optional for tool registries that + support aliases. + + If provided will only return entries with the given alias. + schema: + type: string + - name: toolClass + in: query + description: Filter tools by the name of the subclass (#/definitions/ToolClass) + schema: + type: string + - name: descriptorType + in: query + description: Filter tools by the name of the descriptor type + schema: + $ref: '#/components/schemas/DescriptorType' + - name: tags + in: query + description: Filter tools by registry specific tags + schema: + type: array + items: + type: string + minItems: 1 + explode: false + - name: registry + in: query + description: The image registry that contains the image. + schema: + type: string + - name: organization + in: query + description: The organization in the registry that published the image. + schema: + type: string + - name: name + in: query + description: The name of the image. + schema: + type: string + - name: toolname + in: query + description: The name of the tool. + schema: + type: string + - name: description + in: query + description: The description of the tool. + schema: + type: string + - name: author + in: query + description: The author of the tool (TODO a thought occurs, are we assuming that + the author of the CWL and the image are the same?). + schema: + type: string + - name: checker + in: query + description: Return only checker workflows. + schema: + type: boolean + - $ref: "#/components/parameters/offset" + - $ref: "#/components/parameters/limit" + responses: + "200": + description: An array of Tools that match the filter. + headers: + next_page: + description: A URL that can be used to reach the next page based on the current + offset and page record limit. + schema: + type: string + last_page: + description: A URL that can be used to reach the last page based on the current + page record limit. + schema: + type: string + self_link: + description: A URL that can be used to return to the current page later. + schema: + type: string + current_offset: + description: The current start index of the paging used for this result. + schema: + type: string + current_limit: + description: The current page record limit used for this result. + schema: + type: integer + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Tool" + # security: + # - BEARER: [] + "/tools/{id}/versions/{version_id}/{type}/descriptor": + get: + summary: Get the tool descriptor for the specified tool + operationId: toolsIdVersionsVersionIdTypeDescriptorGet + description: Returns the descriptor for the specified tool (examples include + CWL, WDL, Nextflow, Galaxy, or Snakemake documents). + tags: + - GA4GH + parameters: + - $ref: "#/components/parameters/id" + - $ref: "#/components/parameters/type" + - $ref: "#/components/parameters/version_id" + responses: + "200": + description: The tool descriptor. + content: + application/json: + schema: + $ref: "#/components/schemas/FileWrapper" + text/plain: + schema: + type: string + "404": + description: The tool descriptor can not be found. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + # security: + # - BEARER: [] + "/tools/{id}/versions/{version_id}/{type}/descriptor/{relative_path}": + get: + summary: Get additional tool descriptor files relative to the main file + operationId: toolsIdVersionsVersionIdTypeDescriptorRelativePathGet + description: Descriptors can often include imports that refer to additional + descriptors. This returns additional descriptors for the specified tool + in the same or other directories that can be reached as a relative path. + This endpoint can be useful for workflow engine implementations like + cwltool to programmatically download all the descriptors for a tool and + run it. This can optionally include other files described with + FileWrappers such as test parameters and containerfiles. + tags: + - GA4GH + parameters: + - $ref: "#/components/parameters/id" + - $ref: "#/components/parameters/type" + - $ref: "#/components/parameters/version_id" + - name: relative_path + in: path + required: true + description: A relative path to the additional file (same directory or + subdirectories), for example 'foo.cwl' would return a 'foo.cwl' from + the same directory as the main descriptor. 'nestedDirectory/foo.cwl' + would return the file from a nested subdirectory. Unencoded paths + such 'sampleDirectory/foo.cwl' should also be allowed. + schema: + type: string + pattern: .+ + responses: + "200": + description: The tool descriptor. + content: + application/json: + schema: + $ref: "#/components/schemas/FileWrapper" + text/plain: + schema: + type: string + "404": + description: The tool can not be output in the specified type. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + # security: + # - BEARER: [] + "/tools/{id}/versions/{version_id}/{type}/tests": + get: + summary: Get a list of test JSONs + operationId: toolsIdVersionsVersionIdTypeTestsGet + description: Get a list of test JSONs (these allow you to execute the tool + successfully) suitable for use with this descriptor type. + tags: + - GA4GH + parameters: + - $ref: "#/components/parameters/id" + - $ref: "#/components/parameters/type" + - $ref: "#/components/parameters/version_id" + responses: + "200": + description: The tool test JSON response. + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/FileWrapper" + text/plain: + schema: + type: array + items: + $ref: "#/components/schemas/FileWrapper" + "404": + description: The tool can not be output in the specified type. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + # security: + # - BEARER: [] + "/tools/{id}/versions/{version_id}/{type}/files": + get: + summary: Get a list of objects that contain the relative path and file type + description: Get a list of objects that contain the relative path and file type. + The descriptors are intended for use with the + /tools/{id}/versions/{version_id}/{type}/descriptor/{relative_path} + endpoint. Returns a zip file of all files when format=zip is specified. + operationId: toolsIdVersionsVersionIdTypeFilesGet + tags: + - GA4GH + parameters: + - $ref: "#/components/parameters/id" + - name: type + required: true + in: path + description: The output type of the descriptor. + schema: + $ref: '#/components/schemas/DescriptorType' + - $ref: "#/components/parameters/version_id" + - name: format + in: query + required: false + description: Returns a zip file of all files when format=zip is specified. + schema: + type: string + enum: + - zip + responses: + "200": + description: The array of File JSON responses. + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ToolFile" + application/zip: + schema: + type: array + items: + $ref: "#/components/schemas/ToolFile" + "404": + description: The tool can not be output in the specified type. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + # security: + # - BEARER: [] + "/tools/{id}/versions/{version_id}/containerfile": + get: + summary: Get the container specification(s) for the specified image. + operationId: toolsIdVersionsVersionIdContainerfileGet + description: Returns the container specifications(s) for the specified image. + For example, a CWL CommandlineTool can be associated with one + specification for a container, a CWL Workflow can be associated with + multiple specifications for containers. + tags: + - GA4GH + parameters: + - $ref: "#/components/parameters/id" + - $ref: "#/components/parameters/version_id" + responses: + "200": + description: The tool payload. + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/FileWrapper" + "404": + description: There are no container specifications for this tool. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + # security: + # - BEARER: [] + /toolClasses: + get: + summary: List all tool types + operationId: toolClassesGet + description: | + This endpoint returns all tool-classes available. + tags: + - GA4GH + responses: + "200": + description: A list of potential tool classes. + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ToolClass" + # security: + # - BEARER: [] +externalDocs: + description: Description of GA4GH Tool Registry (Exchange) Schema + url: https://github.com/ga4gh/tool-registry-schemas +servers: + - url: /ga4gh/trs/v2 +components: + parameters: + version_id: + name: version_id + in: path + required: true + description: An identifier of the tool version, scoped to this registry, for + example `v1`. We recommend that versions use semantic versioning + https://semver.org/spec/v2.0.0.html (For example, `1.0.0` instead + of `develop`) + schema: + type: string + type: + name: type + required: true + in: path + description: The output type of the descriptor. Plain types return the bare + descriptor while the "non-plain" types return a descriptor wrapped + with metadata. + schema: + $ref: '#/components/schemas/DescriptorTypeWithPlain' + id: + name: id + in: path + required: true + description: A unique identifier of the tool, scoped to this registry, for + example `123456`. + schema: + type: string + limit: + name: limit + in: query + description: Amount of records to return in a given page. + schema: + type: integer + format: int32 + default: 1000 + offset: + name: offset + in: query + description: Start index of paging. Pagination results can be based on numbers + or other values chosen by the registry implementor (for example, SHA + values). If this exceeds the current result set return an empty set. If + not specified in the request, this will start at the beginning of the + results. + schema: + type: string + # securitySchemes: + # BEARER: + # type: apiKey + # name: Authorization + # in: header + schemas: + Checksum: + type: object + required: + - checksum + - type + properties: + checksum: + type: string + description: "The hex-string encoded checksum for the data. " + type: + type: string + description: >- + The digest method used to create the checksum. + + The value (e.g. `sha-256`) SHOULD be listed as `Hash Name String` in the https://github.com/ga4gh-discovery/ga4gh-checksum/blob/master/hash-alg.csv[GA4GH Checksum Hash Algorithm Registry]. + + Other values MAY be used, as long as implementors are aware of the issues discussed in https://tools.ietf.org/html/rfc6920#section-9.4[RFC6920]. + + GA4GH may provide more explicit guidance for use of non-IANA-registered algorithms in the future. + ToolFile: + type: object + properties: + path: + type: string + description: Relative path of the file. A descriptor's path can be used with + the GA4GH .../{type}/descriptor/{relative_path} endpoint. + file_type: + type: string + enum: + - TEST_FILE + - PRIMARY_DESCRIPTOR + - SECONDARY_DESCRIPTOR + - CONTAINERFILE + - OTHER + checksum: + $ref: "#/components/schemas/Checksum" + ToolClass: + type: object + description: Describes a class (type) of tool allowing us to categorize + workflows, tasks, and maybe even other entities (such as services) + separately. + properties: + id: + type: string + description: The unique identifier for the class. + name: + type: string + description: A short friendly name for the class. + description: + type: string + description: A longer explanation of what this class is and what it can + accomplish. + Tool: + type: object + description: A tool (or described tool) is defined as a tuple of a descriptor + file (which potentially consists of multiple files), a set of container + images, and a set of instructions for creating those images. + required: + - url + - id + - organization + - toolclass + - versions + properties: + url: + type: string + example: http://agora.broadinstitute.org/tools/123456 + description: The URL for this tool in this registry. + id: + type: string + example: 123456 + description: A unique identifier of the tool, scoped to this registry. + aliases: + type: array + items: + type: string + example: + - 630d31c3-381e-488d-b639-ce5d047a0142 + - dockstore.org:630d31c3-381e-488d-b639-ce5d047a0142 + - bio.tools:630d31c3-381e-488d-b639-ce5d047a0142 + description: >- + Support for this parameter is optional for tool registries that + support aliases. + + A list of strings that can be used to identify this tool which could be straight up URLs. + + This can be used to expose alternative ids (such as GUIDs) for a tool + + for registries. Can be used to match tools across registries. + organization: + type: string + description: The organization that published the image. + name: + type: string + description: The name of the tool. + toolclass: + $ref: "#/components/schemas/ToolClass" + description: + type: string + description: The description of the tool. + meta_version: + type: string + description: The version of this tool in the registry. Iterates when fields like + the description, author, etc. are updated. + has_checker: + type: boolean + description: Whether this tool has a checker tool associated with it. + checker_url: + type: string + description: Optional url to the checker tool that will exit successfully if + this tool produced the expected result given test data. + versions: + description: A list of versions for this tool. + type: array + items: + $ref: "#/components/schemas/ToolVersion" + ToolVersion: + type: object + description: A tool version describes a particular iteration of a tool as + described by a reference to a specific image and/or documents. + required: + - url + - id + properties: + author: + type: array + items: + type: string + description: Contact information for the author of this version of the tool in + the registry. (More complex authorship information is handled by the + descriptor). + name: + type: string + description: The name of the version. + url: + type: string + description: The URL for this tool version in this registry. + example: http://agora.broadinstitute.org/tools/123456/versions/1 + id: + type: string + description: An identifier of the version of this tool for this particular tool + registry. + example: v1 + is_production: + type: boolean + description: This version of a tool is guaranteed to not change over time (for + example, a tool built from a tag in git as opposed to a branch). A + production quality tool is required to have a checksum + images: + description: All known docker images (and versions/hashes) used by this tool. If + the tool has to evaluate any of the docker images strings at + runtime, those ones cannot be reported here. + type: array + items: + $ref: "#/components/schemas/ImageData" + descriptor_type: + type: array + description: The type (or types) of descriptors available. + items: + $ref: "#/components/schemas/DescriptorType" + descriptor_type_version: + type: object + description: A map providing information about the language versions used in this tool. The keys should be the + same values used in the `descriptor_type` field, and the value should be an array of all the language versions used + for the given `descriptor_type`. Depending on the `descriptor_type` (e.g. CWL) multiple version values may be used + in a single tool. + example: | + { + "WDL": ["1.0", "1.1"], + "CWL": ["v1.0.2"], + "NFL": ["DSL2"] + } + additionalProperties: + type: array + items: + $ref: "#/components/schemas/DescriptorTypeVersion" + containerfile: + type: boolean + description: Reports if this tool has a containerfile available. (For + Docker-based tools, this would indicate the presence of a + Dockerfile) + description: + type: string + description: The description of the tool version. This allows for documentation of a specific tool version as a tool evolves over time. + meta_version: + type: string + description: The version of this tool version in the registry. Iterates when + fields like the description, author, etc. are updated. + verified: + type: boolean + description: Reports whether this tool has been verified by a specific + organization or individual. + verified_source: + type: array + items: + type: string + description: Source of metadata that can support a verified tool, such as an + email or URL. + signed: + type: boolean + description: Reports whether this version of the tool has been signed. + included_apps: + description: An array of IDs for the applications that are stored inside this + tool. + example: + - https://bio.tools/tool/mytum.de/SNAP2/1 + - https://bio.tools/bioexcel_seqqc + type: array + items: + type: string + ImageData: + type: object + description: Describes one container image. + properties: + registry_host: + type: string + description: A docker registry or a URL to a Singularity registry. Used along + with image_name to locate a specific image. + # example: + # - registry.hub.docker.com + image_name: + type: string + description: Used in conjunction with a registry_url if provided to locate images. + # example: + # - quay.io/seqware/seqware_full/1.1 + # - ubuntu:latest + size: + type: integer + description: Size of the container in bytes. + updated: + type: string + description: Last time the container was updated. + checksum: + type: array + items: + $ref: "#/components/schemas/Checksum" + description: A production (immutable) tool version is required to have a + hashcode. Not required otherwise, but might be useful to detect + changes. This exposes the hashcode for specific image versions to + verify that the container version pulled is actually the version + that was indexed by the registry. + example: + - checksum: 77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182 + type: sha256 + image_type: + $ref: "#/components/schemas/ImageType" + ImageType: + type: string + description: Indicates what kind of container is this image is. + enum: + - Docker + - Singularity + - Conda + DescriptorType: + type: string + description: The type of descriptor that represents this version of the tool. Note that these files can also include + associated Docker/container files and test parameters that further + describe a version of a tool. + enum: + - CWL + - WDL + - NFL + - GALAXY + - SMK + DescriptorTypeVersion: + type: string + description: The language version for a given descriptor type. The version should correspond + to the actual declared version of the descriptor. For example, tools defined in CWL could have a version of `v1.0.2` + whereas WDL tools may have a version of `1.0` or `draft-2` + DescriptorTypeWithPlain: + type: string + description: The output type of the descriptor. Plain types return the raw text while the "non-plain" types return the application/json + enum: + - CWL + - WDL + - NFL + - GALAXY + - SMK + - PLAIN_CWL + - PLAIN_WDL + - PLAIN_NFL + - PLAIN_GALAXY + - PLAIN_SMK + FileWrapper: + type: object + description: > + A file provides content for one of + + - A tool descriptor is a metadata document that describes one or more tools. + + - A tool document that describes how to test with one or more sample test + + JSON. + + - A containerfile is a document that describes how to build a particular + + container image. Examples include Dockerfiles for creating Docker images + + and Singularity recipes for Singularity images + properties: + content: + type: string + description: The content of the file itself. One of url or content is required. + checksum: + type: array + items: + $ref: "#/components/schemas/Checksum" + description: "A production (immutable) tool version is required to have a + hashcode. Not required otherwise, but might be useful to detect + changes. " + example: + - checksum: ea2a5db69bd20a42976838790bc29294df3af02b + type: sha1 + image_type: + description: "Optionally return additional information on the type of file this is" + oneOf: + - $ref: "#/components/schemas/ImageType" + - $ref: "#/components/schemas/DescriptorType" + url: + type: string + description: Optional url to the underlying content, should include version + information, and can include a git hash. Note that this URL should + resolve to the raw unwrapped content that would otherwise be + available in content. One of url or content is required. + # example: + # descriptorfile: + # url: https://raw.githubusercontent.com/ICGC-TCGA-PanCancer/pcawg_delly_workflow/ea2a5db69bd20a42976838790bc29294df3af02b/delly_docker/Delly.cwl + # containerfile: + # url: https://raw.githubusercontent.com/ICGC-TCGA-PanCancer/pcawg_delly_workflow/c83478829802b4d36374870843821abe1b625a71/delly_docker/Dockerfile + Error: + type: object + required: + - code + properties: + code: + type: integer + format: int32 + default: 500 + message: + type: string + default: Internal Server Error \ No newline at end of file diff --git a/trs_filer/config.yaml b/trs_filer/config.yaml index 0dda656..8eae0f2 100644 --- a/trs_filer/config.yaml +++ b/trs_filer/config.yaml @@ -35,7 +35,7 @@ api: specs: - path: - api/20200131.11d2c12.service-info.yaml - - api/20200728.1059c7c.openapi.yaml + - api/20230406.1dd4bf8.openapi.yaml - api/additions.openapi.yaml append: null add_operation_fields: diff --git a/trs_filer/version.py b/trs_filer/version.py index 3ee4751..27473d2 100644 --- a/trs_filer/version.py +++ b/trs_filer/version.py @@ -1,3 +1,3 @@ """Single source of truth for package version.""" -__version__ = '0.2.0' +__version__ = '0.3.0'