TRS-Filer

Lightweight, flexible implementation of the Global Alliance for Genomics & Health's (GA4GH) Tool Registry Service (TRS) API for listing and describing tools and workflows.

Description

TRS-Filer is complete

Next to the endpoints defined by the GA4GH TRS API (see specification and additional documentation), TRS-Filer provides endpoints to register tools, tool versions, tool classes and update the service info.

Note that TRS-Filer is currently not yet 100% compliant with the TRS specification. See the issue tracker to find out which features are still missing!

TRS-Filer is extensible

TRS-Filer makes use of the FOCA microservice archetype, which is based on the Flask / OpenAPI / Connexion tool stack. As FOCA abstracts a lot of boilerplate code away, the TRS-Filer codebase is very small and consists almost exlusively of business logic, making it easy to adapt, extend and maintain.

TRS-Filer is versatile

TRS-Filer was not built on top of a specific tool registry. In cases where the TRS specification leaves things up for implementers, we tried our best to support multiple configurable options.

You can use TRS-Filer as a ready-made, low maintenance shim around your own tool registry and thus make it available to the GA4GH Cloud community. But you can just as well use it to index an available third-party tool registry to have it integrate seamlessly with your GA4GH Cloud ecosystem, or use it to internally represent tools and workflows in your microservice-based web application!

TRS-Filer is free

TRS-Filer is released under a permissive license that lets everyone use it, in every way, for whatever purpose, including commercial.

Usage

Once deployed, the API is served here:

http://localhost:8080/ga4gh/trs/v2/

Note that host (localhost) and port (8080) in the URL above may differ, depending on how the service was deployed. Indicated values are for docker-compose-based installations using the default configuration.

The easiest way to explore available endpoints is via the Swagger UI:

http://localhost:8080/ga4gh/trs/v2/ui

You can also access TRS-Filer's OpenAPI specification:

http://localhost:8080/ga4gh/trs/v2/openapi.json

TRS-Filer endpoints can be queried by sending appropriate HTTP requests to URLs composed of the root API path and an endpoint-specific suffix. For instance, you can list available tools in a TRS-Filer deployment by sending a GET HTTP request to the /tools route, e.g., via curl:

curl -X GET "http://localhost:8080/ga4gh/trs/v2/tools" -H "accept: application/json"

Convenient clients that help with sending HTTP requests and processing responses are available for any major programming language. If you are new to web programming, we recommend you to read up on HTTP methods and web APIs.

Installation

To quickly install the service for development/testing purposes, we recommend deployment via docker-compose, as described below. For more durable deployments on cloud native infrastructure, we also provide a Helm chart and basic deployment instructions (details may need to be adapted for your specific infrastructure).

Requirements

The following software needs to be available on your system:

• git v2.17.1
• docker v18.09.6
• docker-compose v1.23.1

Indicated versions were used during development. Other versions may work as well, especially newer ones.

Deployment

First, clone the repository and traverse into the service's root directory with:

git clone [email protected]:elixir-cloud-aai/trs-filer.git
cd trs-filer

Then simply start up the service with:

docker-compose up --build -d

That's it!

You should now be able to use/explore the API as described in the usage section.

Other useful commands

To shut down the service, run:

docker-compose down

If you need to inspect the logs, call:

docker-compose logs

Configuration

The app's configuration is centralized in the file trs_filer/config.yaml. As the format follows the one expected by FOCA, refer to the FOCA documentation for a description of the various configuration options.

The only exception to this is the custom section endpoints, which lists all the configuration options that are specific to TRS-Filer. These are:

• service: The parameters in this section are used to construct self references/anchors as required by the TRS specification and need to be replaced with the corresponding values of each individual TRS-Filer deployment.
• service-info: The parameters in this section are used to populate the service info database collection if such a collection does not yet exist, usually when a new app instance is deployed. The default values should be replaced for each individual deployment, in accordance with the schemas and documentation provided in the GA4GH Service Info specification.
• tool, version & toolclass: The parameters in these sections define the behavior for generating the id and meta_version identifiers for tools, tool versions and tool classes, respectively, as required by the TRS specification.
  • For id-type identifiers, random strings of a specified length are generated from a set of allowed characters (charset). The latter option accepts either a string, indicating the allowed characters, or a Python expression that evaluates to such a string.
  • For meta_version-type identifiers, increasing natural numbers are generated that start with the value of init and are increased by increment for each new resource.

Extension

It is easy to add additional endpoints or modify the behavior of existing ones.

All OpenAPI specifications are available in trs_filer.api. Custom endpoints, i.e., those that are not specified in either the GA4GH TRS or the GA4GH Service Info specifications, are included in file additions.openapi.yaml.

When specifying new endpoints, the operationId directive indicates the name of the corresponding controller. By default, all controllers need to be implemented in the ga4gh.trs.server module. For example, when specifying an operationId of myController for a new endpoint in additions.openapi.yaml, the application would expect the corresponding controller to be implemented in function/class ga4gh.trs.server.myController().

If necessary, the default location of the module containing the controllers can be customized following instructions provided by FOCA, Connexion and OpenAPI.

Custom errors can be specified in module errors.exceptions. Just follow the existing structure and refer the FOCA documentation on exception handling in case of doubt.

Contributing

This project is a community effort and lives off your contributions, be it in the form of bug reports, feature requests, discussions, or fixes and other code changes. Please refer to our organization's contribution guidelines if you are interested in contributing. Please mind the code of conduct for all interactions with the community.

Versioning

The project adopts the semantic versioning scheme for versioning. Currently the service is in beta stage, so the API may change without further notice.

License

This project is covered by the Apache License 2.0 also shipped with this repository.

Contact

The project is a collaborative effort under the umbrella of ELIXIR Cloud & AAI. Follow the link to get in touch with us via chat or email. Please mention the name of this service for any inquiry, proposal, question etc. Alternatively, you can also make use of the issue tracker to request features or report bugs.