Service registry is a GA4GH service providing information about other GA4GH services, primarily for the purpose of organizing services into networks or groups and service discovery across organizational boundaries. Information about the individual services in the registry is described in a complementary service-info specification.
The specification is useful whenever you're dealing with technologies that handle multiple GA4GH services. Common use cases include creating networks or groups of services of a certain type (e.g. Beacon Network searches networks of Beacon services across multiple organizations, a workflow can be executed by a specific group of Workflow Execution Services, or Search on biomedical data is federated across a set of nodes), or a certain host (e.g. an organization provides provides implementations of Beacon, Search and Data Repository Service APIs, or a server hosts an implementation of refget and htsget APIs).
Service registry API is specified in OpenAPI in service-registry.yaml, which you can view using Swagger Editor.
There are two ways to implement this specifications - directly (e.g. a registry of services hosted by an institution), or indirectly through an upstream specification (e.g. an implementation of the Beacon Network specification, which itself provides registry functionality by extending this specification).
When implementing a registry directly, please use the following as your service type under /service-info.
"type": {
"group": "org.ga4gh",
"artifact": "service-registry",
"version": "1.0.0"
}When implementing a registry indirectly, rely on the upstream specification for guidance on the service type to use.
Sometimes, for example when implementing a specification extending this specification, you might want to include additional information not easily captured by fields currently specified in our schemas. In such situations, we recommend you add custom fields directly as top-level fields in your schemas, as recommended by service-info.
Service registry is useful for discovering where other services live, even if their locations change over time. As such, we recommend you deploy your service registry implementation with a stable URL, and use it to anchor variable URLs of other services for your clients.
Feel free to check out our reference implementation.
Service metadata is viewed as public data and can be provided without restriction. However, an implementation may choose to distribute additional metadata, which may be considered sensitive. Effective security measures are essential to protect the integrity and confidentiality of this data.
Sensitive information transmitted over public networks, such as access tokens and human genomic data, MUST be protected using Transport Level Security (TLS) version 1.2 or later, as specified in RFC 5246.
If the data holder requires client authentication and/or authorization, then the client’s HTTPS API request MUST present an OAuth 2.0 bearer access token as specified in RFC 6750, in the Authorization request header field with the Bearer authentication scheme:
Authorization: Bearer [access_token]
The policies and processes used to perform user authentication and authorization, and the means through which access tokens are issued, are beyond the scope of this API specification. GA4GH recommends the use of the OpenID Connect and OAuth 2.0 framework (RFC 6749) for authentication and authorization.
Cross-origin resource sharing (CORS) is an essential technique used to overcome the same origin content policy seen in browsers. This policy restricts a webpage from making a request to another website and leaking potentially sensitive information. However the same origin policy is a barrier to using open APIs. GA4GH open API implementers should enable CORS to an acceptable level as defined by their internal policy. For any public API implementations should allow requests from any server.
GA4GH published a CORS best practices document, which implementers should refer to for guidance when enabling CORS on public API instances.
Use Swagger Validator Badge to validate the YAML file, or its OAS Validator wrapper.
Guidelines for contributing to this repository are listed in CONTRIBUTING.md.
Please send an email to security-notification@ga4gh.org.
- Don't prescribe pagination (#71).
- Don't compromise design in favour of static no-code implementation (#71).
- When extending the specification, add custom fields directly as top-level fields in your schemas - no need to nest in a particular field (service-info/issues/35).
General-purpose service registries you might know from microservices (like Eureka or Consul) are designed to allow services to programmatically discover other services in their environment. They work within organizational boundaries and rely on the environment being under your control. They use custom proprietary APIs and are fairly heavy-weight (provide a lot of additional functionality like rich health checking, multi-datacenter awareness, service management).
This service registry is a minimalistic, light-weight, read-only, standard API. It's designed to aggregate services from many organizations across organizational boundaries, without imposing communication restrictions on these services, or even requiring them to be aware of the registry they're a part of. Rather than internal service-service discovery, this registry is often used to advertise services to arbitrary clients outside of the service organization. The registry is GA4GH-aware and supports metadata specific to GA4GH web services.
Yes, you're welcome to list arbitrary services in your registry. This specification relies on the service-info specification, which supports arbitrary service types.
While there's no inherent support for structure within a group of services exposed by the registry, a service registry can list other service registries amongst its services. It is then the responsibility of the client to crawl through the graph to discover all the services available in the network. Alternatively, you can perform such crawling in your implementation of the service registry server. While this eases the burden on the client, it comes at the cost of losing the structure of the network, and maintaining the list of services in sync across registries.
The following people have contributed to the design of this specification.
- Miro Cupak
- Andy Yates
- Jordi Rambla
- Milan Panik
- Juha Tonroos