GA4GH Planet API (0.5.0)

Download OpenAPI specification:Download

GA4GH Tech Team: jeremy.adams@ga4gh.org URL: https://ga4gh.org License: Apache 2.0

Introduction

The Planet API is an HTTP API served by the Global Alliance for Genomics and Health (GA4GH).

The API contains metadata about GA4GH deliverables (ie. technical specifications, policy frameworks, ongoing data sharing initiatives), including product review lifecycle status, released versions, and tools for working with the standards.

Planet API is also a GA4GH Service Registry, implementing the Service Registry Specification. As such, it is possible to search the registry for web services implementing GA4GH API specifications (e.g. htsget, drs, beacon). The registry is filterable based on service type. At this time, only publicly accessible web services are listed.

Implementations vs. Services

The API distinguishes between implementations and services.

In this context, an implementation refers to any codebase that works with one or more GA4GH standards. Examples include:

  • client libraries for accessing data from GA4GH APIs
  • command-line tools/executables for reading/writing GA4GH format files
  • codebases that can be run to spin-up a GA4GH API server
  • Other tools involving complex analyses that make use of GA4GH standards

A service refers to a running web server serving genomic data according to a GA4GH API specification.

Implementations and services can be accessed via the /implementations and /services routes, respectively.

Register an implementation or web service

To register an implementation or web service in the Planet API registry, please complete and submit the registration form.

Once completed, someone from the GA4GH Technical Team will then register your item, or contact you if more information is needed.

Errors

The API uses standard rfc2616 HTTP status codes to indicate the success or failure of the API call. The body of an error response will be in JSON in the following format:

{
    "timestamp": "2020-08-14T17:14:13Z",
    "status": 404,
    "error": "Not Found",
    "message": "no Implementation by the id: example1",
    "path": "/v1/services/example1"
}

Authentication

BearerAuth

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Service Info

/service-info API endpoint(s) return information about this web service, according to the GA4GH Service Info specification

Get service info

Get information about this service

Responses

Response samples

Content type
application/json
{
  • "id": "org.ga4gh.myimplementation",
  • "name": "My project",
  • "type":
    {
    },
  • "description": "This implementation of the Beacon API specification ...",
  • "organization":
    {
    },
  • "contactUrl": "mailto:support@example.com",
  • "documentationUrl": "http://example.com",
  • "createdAt": "2019-06-04T12:58:19Z",
  • "updatedAt": "2019-06-04T12:58:19Z",
  • "version": "1.0.0",
  • "environment": "test",
}

Standards

/standards API endpoints are used to retrieve information about GA4GH standards from the registry, or otherwise create, modify, or delete them.

List standards

Get entire list of GA4GH standards. This endpoint shows only high-level info about each standard. For detailed information about a particular standard, see Get standard by Id

Responses

Response samples

Content type
application/json
[]

Create standard

Create a new standard with the information specified in requestBody

Authorizations:
Request Body schema: application/json

new standard to create

id
required
string

unique identifier

name
required
string

official name

abbreviation
string

abbreviation/acronym

artifact
string

canonical artifact value for services adopting this specification. See service-info and the service-info type registry

summary
required
string

single-sentence summary of standard

documentationUrl
required
string

url to specification homepage

category
required
string
Enum: "API" "FileFormat" "Schema" "Policy"

broad classification of standard category

status
required
string
Enum: "Proposed" "Approved" "Deprecated"

release status of standard

description
required
string

longer description of standard

required
Array of objects (StandardVersion)

list of versioned releases associated with the specification

required
object (WorkStream)

represents a technical or foundational GA4GH Work Stream

Responses

Request samples

Content type
application/json
{
  • "id": "drs",
  • "name": "Data Repository Service",
  • "abbreviation": "DRS",
  • "artifact": "drs",
  • "summary": "Platform-agnostic data API",
  • "category": "API",
  • "status": "Approved",
  • "description": "The Data Repository Service (DRS) API, a standard for building data repositories and adapting access tools to work with those repositories, works with other approved APIs from the GA4GH Cloud Work Stream to allow researchers to discover algorithms across different cloud environments and send them to datasets they wish to analyze.",
  • "versions":
    [],
  • "workStream":
    {
    }
}

Response samples

Content type
application/json
{
  • "id": "drs",
  • "name": "Data Repository Service",
  • "abbreviation": "DRS",
  • "artifact": "drs",
  • "summary": "Platform-agnostic data API",
  • "category": "API",
  • "status": "Approved",
  • "description": "The Data Repository Service (DRS) API, a standard for building data repositories and adapting access tools to work with those repositories, works with other approved APIs from the GA4GH Cloud Work Stream to allow researchers to discover algorithms across different cloud environments and send them to datasets they wish to analyze.",
  • "versions":
    [],
  • "workStream":
    {
    }
}

Get standard by id

Show detailed information about a single standard, including versions and work stream

path Parameters
standardId
any
Example: drs

unique identifier for the standard

Responses

Response samples

Content type
application/json
{
  • "id": "drs",
  • "name": "Data Repository Service",
  • "abbreviation": "DRS",
  • "artifact": "drs",
  • "summary": "Platform-agnostic data API",