TRS Providers

The @elixir-cloud/trs package provides providers for connecting to GA4GH Tool Registry Service (TRS) APIs. The main provider is RestTrsProvider which implements the TrsProvider interface for REST-based TRS endpoints.

Quick Start: Create a RestTrsProvider with your TRS server URL and pass it to TRS components to start browsing tools and workflows.

TrsProvider Interface

The TrsProvider interface defines the operations that all TRS providers must implement:

export interface TrsProvider {
  // List view methods
  getToolClasses(): Promise<ToolClass[]>;
  getToolsList(
    limit: number,
    offset: number,
    filters: Record<string, string | undefined | boolean>,
    query: string
  ): Promise<Tool[]>;
 
  // Detail view methods
  getTool(url: string, id: string): Promise<Tool>;
  getToolVersions(url: string, id: string): Promise<ToolVersion[]>;
  getToolVersion(url: string, id: string, versionId: string): Promise<ToolVersion>;
  getToolFiles(
    url: string,
    id: string,
    version: string,
    descriptorType: DescriptorType,
    format?: "zip"
  ): Promise<ToolFile[]>;
  getToolDescriptor(
    url: string,
    id: string,
    version: string,
    descriptorType: DescriptorType
  ): Promise<FileWrapper>;
  getToolDescriptorByPath(
    url: string,
    id: string,
    version: string,
    descriptorType: DescriptorType,
    path: string
  ): Promise<FileWrapper>;
  getContainerfile(url: string, id: string, version: string): Promise<FileWrapper[]>;
  getToolTests(
    url: string,
    id: string,
    version: string,
    descriptorType: DescriptorType
  ): Promise<FileWrapper[]>;
}

RestTrsProvider

The RestTrsProvider is the main implementation that communicates with TRS APIs using REST/HTTP.

Constructor

constructor(baseUrl: string)

Parameters:

baseUrl: The base URL of the TRS API endpoint (e.g., https://dockstore.org/api/ga4gh/trs/v2)

Basic Usage

import { RestTrsProvider } from '@elixir-cloud/trs/providers';
import { EccClientGa4ghTrsTools } from '@elixir-cloud/trs';
 
function ToolBrowser() {
  const provider = new RestTrsProvider(
    'https://dockstore.org/api/ga4gh/trs/v2'
  );
 
  return (
    <div>
      <h2>Available Tools</h2>
      <EccClientGa4ghTrsTools provider={provider} />
    </div>
  );
}

Provider Methods

getToolClasses()

Retrieves all available tool classes.

getToolClasses(): Promise<ToolClass[]>

getToolsList()

Gets a list of tools with filtering and pagination.

getToolsList(
  limit: number,
  offset: number,
  filters: Record<string, string | undefined | boolean>,
  query: string
): Promise<Tool[]>

getTool()

Gets detailed information about a specific tool.

getTool(url: string, id: string): Promise<Tool>

getToolVersions()

Retrieves all versions available for a specific tool.

getToolVersions(url: string, id: string): Promise<ToolVersion[]>

getToolVersion()

Gets detailed information about a specific tool version.

getToolVersion(url: string, id: string, versionId: string): Promise<ToolVersion>

getToolFiles()

Gets the list of files associated with a tool version.

getToolFiles(
  url: string,
  id: string,
  version: string,
  descriptorType: DescriptorType,
  format?: "zip"
): Promise<ToolFile[]>

getToolDescriptor()

Retrieves the descriptor file (CWL, WDL, etc.) for a tool version.

getToolDescriptor(
  url: string,
  id: string,
  version: string,
  descriptorType: DescriptorType
): Promise<FileWrapper>

getToolDescriptorByPath()

Gets a specific descriptor file by path.

getToolDescriptorByPath(
  url: string,
  id: string,
  version: string,
  descriptorType: DescriptorType,
  path: string
): Promise<FileWrapper>

getContainerfile()

Retrieves containerfiles for a tool version.

getContainerfile(url: string, id: string, version: string): Promise<FileWrapper[]>

getToolTests()

Gets test files for a tool version.

getToolTests(
  url: string,
  id: string,
  version: string,
  descriptorType: DescriptorType
): Promise<FileWrapper[]>

Type Definitions

DescriptorType

type DescriptorType = "CWL" | "WDL" | "NFL" | "GALAXY" | "SMK";

DescriptorTypeWithPlain

type DescriptorTypeWithPlain =
  | DescriptorType
  | "PLAIN_CWL"
  | "PLAIN_WDL"
  | "PLAIN_NFL"
  | "PLAIN_GALAXY"
  | "PLAIN_SMK";

DescriptorTypeVersion

interface DescriptorTypeVersion {
  descriptor_type_version: string;
}

ImageType

type ImageType = "Docker" | "Singularity" | "Conda";

Checksum

interface Checksum {
  checksum: string;
  type: string;
}

ImageData

interface ImageData {
  registry_host?: string;
  image_name?: string;
  size?: number;
  updated?: string;
  checksum?: Checksum[];
  image_type?: ImageType;
}

ToolClass

interface ToolClass {
  id: string;
  name: string;
  description?: string;
}

ToolVersion

interface ToolVersion {
  author?: string[];
  name?: string;
  url: string;
  id: string;
  is_production?: boolean;
  images?: ImageData[];
  descriptor_type?: DescriptorType[];
  descriptor_type_version?: Record<DescriptorType, DescriptorTypeVersion[]>;
  containerfile?: boolean;
  description?: string;
  meta_version?: string;
  verified?: boolean;
  verified_source?: string[];
  signed?: boolean;
  included_apps?: string[];
}

Tool

interface Tool {
  url: string;
  id: string;
  aliases?: string[];
  organization: string;
  name?: string;
  toolclass: ToolClass;
  description?: string;
  meta_version?: string;
  has_checker?: boolean;
  checker_url?: string;
  versions: ToolVersion[];
}

ToolFile

interface ToolFile {
  path: string;
  file_type?:
    | "TEST_FILE"
    | "PRIMARY_DESCRIPTOR"
    | "SECONDARY_DESCRIPTOR"
    | "CONTAINERFILE"
    | "OTHER";
  checksum?: Checksum;
}

FileWrapper

interface FileWrapper {
  content?: string;
  url?: string;
  checksum?: Checksum[];
  image_type?: ImageType | DescriptorType;
}

Using with Components

Tool Browsing

import { RestTrsProvider } from '@elixir-cloud/trs/providers';
import { EccClientGa4ghTrsTools } from '@elixir-cloud/trs';
 
function ToolBrowser() {
  const provider = new RestTrsProvider('https://dockstore.org/api/ga4gh/trs/v2');
 
  return (
    <EccClientGa4ghTrsTools 
      provider={provider}
      onEccToolsChanged={(event) => {
        console.log('Tools updated:', event.detail.tools.length);
      }}
      onEccToolsSelected={(event) => {
        console.log('Tool selected:', event.detail.toolId);
      }}
    />
  );
}

Tool Details

import { RestTrsProvider } from '@elixir-cloud/trs/providers';
import { EccClientGa4ghTrsTool } from '@elixir-cloud/trs';
 
function ToolDetails({ toolId }) {
  const provider = new RestTrsProvider('https://dockstore.org/api/ga4gh/trs/v2');
 
  return (
    <EccClientGa4ghTrsTool 
      provider={provider}
      toolId={toolId}
      onEccToolVersionChanged={(event) => {
        console.log('Version changed:', event.detail.version);
      }}
    />
  );
}

Popular TRS Endpoints

Here are some popular TRS endpoints you can use:

// Dockstore (public tool registry)
const dockstoreProvider = new RestTrsProvider('https://dockstore.org/api/ga4gh/trs/v2');
 
// WorkflowHub (workflow registry)
const workflowhubProvider = new RestTrsProvider('https://workflowhub.eu/ga4gh/trs/v2');
 
// BioContainers (container registry)
const biocontainersProvider = new RestTrsProvider('https://api.biocontainers.pro/ga4gh/trs/v2');
 
// Seven Bridges (commercial platform)
const sbgProvider = new RestTrsProvider('https://api.sbgenomics.com/ga4gh/trs/v2');

Custom Providers

For custom use cases, you can extend RestTrsProvider or implement the TrsProvider interface directly. This is useful for:

Adding custom authentication
Implementing caching or offline support
Connecting to non-standard APIs
Adding custom error handling or retry logic

// Example: Custom provider with authentication
class CustomTrsProvider extends RestTrsProvider {
  constructor(baseUrl, apiKey) {
    super(baseUrl);
    this.apiKey = apiKey;
  }
 
  async fetch(url, options = {}) {
    return super.fetch(url, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        ...options.headers
      }
    });
  }
}

For comprehensive patterns and examples, see the Providers Overview documentation.

Testing

Test your TRS provider setup:

async function testTrsProvider(provider) {
  try {
    console.log('Testing TRS provider...');
    
    // Test service info
    const serviceInfo = await provider.getServiceInfo();
    console.log('✅ Service info:', serviceInfo.name);
    
    // Test tool listing
    const tools = await provider.getTools(undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, 5, 0);
    console.log(`✅ Found ${tools.length} tools`);
    
    // Test tool details if tools exist
    if (tools.length > 0) {
      const tool = await provider.getTool(tools[0].id);
      console.log(`✅ Tool details: ${tool.name}`);
    }
    
    console.log('✅ TRS provider is working correctly!');
    return true;
  } catch (error) {
    console.error('❌ TRS provider test failed:', error);
    return false;
  }
}
 
// Usage
const provider = new RestTrsProvider('https://dockstore.org/api/ga4gh/trs/v2');
testTrsProvider(provider);

Next Steps: Check the Providers Overview for patterns on authentication, error handling, caching, and environment configuration that you can apply to your TRS provider.

Introduction Tools