Service Registry Providers

The @elixir-cloud/service-registry package provides providers for connecting to GA4GH Service Registry APIs. The main provider is RestServiceRegistryProvider which implements the ServiceRegistryProvider interface for REST-based service registry endpoints.

Quick Start: Create a RestServiceRegistryProvider with your service registry URL and pass it to Service Registry components to start browsing services.

ServiceRegistryProvider Interface

The ServiceRegistryProvider interface defines the operations that all Service Registry providers must implement:

export interface ServiceRegistryProvider {
  // List services
  getServices(): Promise<ExternalService[]>;
 
  // Get service by ID
  getServiceById(id: string): Promise<ExternalService>;
 
  // Get service types
  getServiceTypes(): Promise<ServiceType[]>;
 
  // Get registry info
  getServiceInfo(): Promise<Service>;
}

RestServiceRegistryProvider

The RestServiceRegistryProvider is the main implementation that communicates with GA4GH Service Registry APIs using REST/HTTP.

Constructor

constructor(baseUrl: string)

Parameters:

baseUrl: The base URL of the Service Registry API endpoint (e.g., https://registry.example.com/ga4gh/registry/v1)

Basic Usage

import { RestServiceRegistryProvider } from '@elixir-cloud/service-registry/providers';
import { EccClientGa4ghServiceRegistryServices } from '@elixir-cloud/service-registry';
 
function ServiceBrowser() {
  const provider = new RestServiceRegistryProvider(
    'https://registry.example.com/ga4gh/registry/v1'
  );
 
  return (
    <div>
      <h2>Available Services</h2>
      <EccClientGa4ghServiceRegistryServices provider={provider} />
    </div>
  );
}

Provider Methods

getServices()

Retrieves all services from the registry.

getServices(): Promise<ExternalService[]>

getServiceById()

Gets detailed information about a specific service.

getServiceById(id: string): Promise<ExternalService>

getServiceTypes()

Retrieves available service types from the registry.

getServiceTypes(): Promise<ServiceType[]>

getServiceInfo()

Gets information about the service registry itself.

getServiceInfo(): Promise<Service>

Type Definitions

ServiceType

interface ServiceType {
  group: string;
  artifact: string;
  version: string;
}

Organization

interface Organization {
  name: string;
  url: string;
}

Service

interface Service {
  id: string;
  name: string;
  type: ServiceType;
  description?: string;
  organization: Organization;
  contactUrl?: string;
  documentationUrl?: string;
  createdAt?: string;
  updatedAt?: string;
  environment?: string;
  version: string;
}

ExternalService

interface ExternalService extends Service {
  url: string;
}

Using with Components

Service Browsing

import { RestServiceRegistryProvider } from '@elixir-cloud/service-registry/providers';
import { EccClientGa4ghServiceRegistryServices } from '@elixir-cloud/service-registry';
 
function ServiceBrowser() {
  const provider = new RestServiceRegistryProvider('https://registry.example.com/ga4gh/registry/v1');
 
  return (
    <EccClientGa4ghServiceRegistryServices 
      provider={provider}
      onEccServicesChanged={(event) => {
        console.log('Services updated:', event.detail.services.length);
      }}
      onEccServiceSelected={(event) => {
        console.log('Service selected:', event.detail.serviceId);
      }}
    />
  );
}

Service Details

import { RestServiceRegistryProvider } from '@elixir-cloud/service-registry/providers';
import { EccClientGa4ghServiceRegistryService } from '@elixir-cloud/service-registry';
 
function ServiceDetails({ serviceId }) {
  const provider = new RestServiceRegistryProvider('https://registry.example.com/ga4gh/registry/v1');
 
  return (
    <EccClientGa4ghServiceRegistryService 
      provider={provider}
      serviceId={serviceId}
      onEccServiceChanged={(event) => {
        console.log('Service details updated:', event.detail.service);
      }}
    />
  );
}

Custom Providers

For custom use cases, you can extend RestServiceRegistryProvider or implement the ServiceRegistryProvider 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 CustomServiceRegistryProvider extends RestServiceRegistryProvider {
  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 Service Registry provider setup:

async function testServiceRegistryProvider(provider) {
  try {
    console.log('Testing Service Registry provider...');
    
    // Test service info
    const serviceInfo = await provider.getServiceInfo();
    console.log('✅ Service info:', serviceInfo.name);
    
    // Test services listing
    const services = await provider.getServices();
    console.log(`✅ Found ${services.length} services`);
    
    // Test service types
    const types = await provider.getServiceTypes();
    console.log(`✅ Found ${types.length} service types`);
    
    // Test service details if services exist
    if (services.length > 0) {
      const service = await provider.getServiceById(services[0].id);
      console.log(`✅ Service details: ${service.name}`);
    }
    
    console.log('✅ Service Registry provider is working correctly!');
    return true;
  } catch (error) {
    console.error('❌ Service Registry provider test failed:', error);
    return false;
  }
}
 
// Usage
const provider = new RestServiceRegistryProvider('https://registry.example.com/ga4gh/registry/v1');
testServiceRegistryProvider(provider);

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

Introduction Services