diff --git a/README.md b/README.md index 5a5206d..32ec136 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,202 @@ -# DRS-filer +# DRS-Filer [![License][badge-license]][badge-url-license] [![Build_status][badge-build-status]][badge-url-build-status] [![Coverage][badge-coverage]][badge-url-coverage] -## Synopsis +Lightweight, flexible implementation of the [Global Alliance for Genomics & +Health's (GA4GH)][ga4gh] [Tool Registry Service (DRS) API][ga4gh-drs] for +listing and describing tools and workflows. -Microservice implementing the [Global Alliance for Genomics and -Health][org-ga4gh] (GA4GH) [Data Repository Service][res-ga4gh-drs] (DRS) -API specification. +## Description +_**DRS-Filer is complete**_ -## Description +Next to the endpoints defined by the GA4GH DRS API (see +[specification][ga4gh-drs], DRS-Filer provides endpoints to register +tools, tool versions, tool classes and update the service info. + +_**DRS-Filer is extensible**_ + +DRS-Filer makes use of the [FOCA][res-foca] microservice archetype, which is +based on the [Flask][res-flask] / [OpenAPI][res-openapi] / +[Connexion][res-connexion] tool stack. As FOCA abstracts a lot of boilerplate +code away, the DRS-Filer codebase is very small and consists almost exlusively +of business logic, making it easy to [adapt, extend and maintain](#extension). + +_**DRS-Filer is versatile**_ + +DRS-Filer was not built on top of a specific data repository. In cases where the +[DRS specification][ga4gh-drs] leaves things up for implementers, we tried +our best to support multiple [configurable options](#configuration). +You can use DRS-Filer as a ready-made, low maintenance shim around your own +data repository and thus make it available to the [GA4GH Cloud][ga4gh-cloud] +community. But you can just as well use it to index an available third-party +data repository to have it integrate seamlessly with your [GA4GH +Cloud][ga4gh-cloud] ecosystem. + +_**DRS-Filer is free**_ + +DRS-Filer is released under a [permissive license][license] that lets everyone +use it, in every way, for whatever purpose, including commercial. ## Usage +Once [deployed](#installation), the API is served here: + +```console +http://localhost:8080/ga4gh/drs/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][drs-filer-compose-config]. + +The easiest way to explore available endpoints is via the +[Swagger UI][res-swagger-ui]: + +```console +http://localhost:8080/ga4gh/drs/v1/ui +``` + +You can also access DRS-Filer's [OpenAPI][res-openapi] specification: + +```console +http://localhost:8080/ga4gh/drs/v1/swagger.json +``` + +DRS-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 DRS-Filer deployment by sending a `GET` HTTP +request to the `/tools` route, e.g., via `curl`: + +```bash +curl -X GET "http://localhost:8080/ga4gh/drs/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][res-http-methods] and [web APIs][res-web-apis]. + +## Installation + +To quickly install the service for development/testing purposes, we recommend +deployment via [`docker-compose`][res-docker-compose], as described below. For +more durable deployments on cloud native infrastructure, we also provide a +[Helm][res-helm] chart and [basic deployment instructions][drs-filer- +deployment] (details may need to be adapted for your specific infrastructure). + +### Requirements + +The following software needs to be available on your system: + +- [`git`][res-git] `v2.17.1` +- [`docker`][res-docker] `v18.09.6` +- [`docker-compose`][res-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: + +```bash +git clone git@github.com:elixir-cloud-aai/drs-filer.git +cd drs-filer +``` + +Then simply start up the service with: + +```bash +docker-compose up --build -d +``` + +_**That't it!**_ + +You should now be able to use/explore the API as described in the [usage +section](#usage). + +### Other useful commands + +To shut down the service, run: + +```bash +docker-compose down +``` + +If you need to inspect the logs, call: + +```bash +docker-compose logs +``` + +## Configuration + +The app's configuration is centralized in the file +[`drs_filer/config.yaml`][drs-filer-config]. As the format follows the one +expected by [FOCA][res-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 DRS-Filer. These are: + +* `service`: The parameters in this section are used to construct self + references/anchors as required by the [DRS specification][ga4gh-drs] and need + to be replaced with the corresponding values of each individual DRS-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][ga4gh-service-info]. +* `objects` & `access_methods`: The parameters in these sections define the + behavior for generating the `id` identifier for objects and access methods, + respectively, as required by the [DRS specification][ga4gh-drs]. + * 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. + +## Extension + +It is easy to add additional endpoints or modify the behavior of existing ones. + +All OpenAPI specifications are available in [`drs_filer.api`][drs-filer-api]. +Custom endpoints, i.e., those that are not specified in either the [GA4GH +DRS][ga4gh-drs] or the [GA4GH Service Info][ga4gh-service-info] specifications, +are included in file [`additional.data_repository_service.swagger.yaml`][drs-filer-api-custom]. + +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.drs.server`][drs-filer-controllers] module. For +example, when specifying an `operationId` of `myController` for a new endpoint +in [`additional.data_repository_service.swagger.yaml`][drs-filer-api-custom], the application would +expect the corresponding controller to be implemented in function/class +`ga4gh.drs.server.myController()`. + +> If necessary, the default location of the module containing the controllers +> can be customized following instructions provided by [FOCA][res-foca], +> [Connexion][res-connexion] and [OpenAPI][res-openapi]. + +Custom errors can be specified in module +[`errors.exceptions`][drs-filer-exceptions]. Just follow the existing structure +and refer the [FOCA][res-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 [contributing -guidelines][res-elixir-cloud-contributing] if you are interested to contribute. -Please mind the [code of conduct][res-elixir-cloud-coc] for all interactions -with the community. +changes. Please refer to our organization's [contribution +guidelines][elixir-cloud-contributing] if you are interested in contributing. +Please mind the [code of conduct][elixir-cloud-coc] for all interactions with +the community. ## Versioning @@ -40,23 +212,48 @@ This project is covered by the [Apache License 2.0][license-apache] also ## Contact The project is a collaborative effort under the umbrella of [ELIXIR Cloud & -AAI][org-elixir-cloud]. 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. +AAI][elixir-cloud]. 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][drs-filer-issues] to request features or report bugs. + +![Logo_banner][img-logo-banner] [badge-build-status]: [badge-coverage]: -[badge-github-tag]: [badge-license]: [badge-url-build-status]: [badge-url-coverage]: -[badge-url-github-tag]: [badge-url-license]: +[elixir-cloud]: +[elixir-cloud-coc]: +[elixir-cloud-contributing]: +[ga4gh]: +[ga4gh-cloud]: +[ga4gh-service-info]: +[ga4gh-drs]: +[ga4gh-drs-docs]: +[img-logo-banner]: images/logo-banner.svg [license]: LICENSE [license-apache]: -[org-elixir-cloud]: -[org-ga4gh]: -[res-elixir-cloud-coc]: -[res-elixir-cloud-contributing]: +[res-connexion]: +[res-docker]: +[res-docker-compose]: +[res-flask]: +[res-foca]: +[res-git]: +[res-helm]: +[res-http-methods]: +[res-openapi]: [res-semver]: -[res-ga4gh-drs]: https://github.com/ga4gh/data-repository-service-schemas +[res-swagger-ui]: +[res-web-apis]: +[drs-filer-api]: drs_filer/api +[drs-filer-api-custom]: drs_filer/api/additional.data_repository_service.swagger.yaml +[drs-filer-compose-config]: docker-compose.yaml +[drs-filer-config]: drs_filer/config.yaml +[drs-filer-controllers]: drs_filer/ga4gh/drs/server.py +[drs-filer-controllers-subpackage]: drs_filer/ga4gh/drs/endpoints +[drs-filer-deployment]: deployment/README.md +[drs-filer-exceptions]: drs_filer/errors/exceptions.py +[drs-filer-issues]: \ No newline at end of file