Global Alliance for Genomics and Health
Documentation Powered by ReDoc

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

The production API base url is: https://registry.ga4gh.org/v1/

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",
  • "url": "http://example.com"
}

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:
BearerAuth
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",
  • "documentationUrl": "https://github.com/ga4gh/data-repository-service-schemas",
  • "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",
  • "documentationUrl": "https://github.com/ga4gh/data-repository-service-schemas",
  • "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",
  • "documentationUrl": "https://github.com/ga4gh/data-repository-service-schemas",
  • "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":
    {
    }
}

Update standard by id

Overwrites the standard at the specified id, with the information specified in requestBody

Authorizations:
BearerAuth
path Parameters
standardId
any
Example: drs

unique identifier for the standard

Request Body schema: application/json

new properties for existing standard object

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",
  • "documentationUrl": "https://github.com/ga4gh/data-repository-service-schemas",
  • "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",
  • "documentationUrl": "https://github.com/ga4gh/data-repository-service-schemas",
  • "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":
    {
    }
}

Delete standard by id

Deletes the standard at the specified id

Authorizations:
BearerAuth
path Parameters
standardId
any
Example: drs

unique identifier for the standard

Responses

Response samples

Content type
application/json
{
  • "timestamp": "2020-08-14T19:56:46Z",
  • "status": 404,
  • "error": "Not Found",
  • "message": "the requested resource could not be located",
  • "path": "/v1/services"
}

Services

/services API endpoints are used to retrieve information about web services implementing GA4GH standards from the registry. These endpoints can also create, modify, or delete registered web services

List services

Gets list of all registered web services matching filtering criteria. Services may be filtered using the type parameter, which will cause the registry to return services of a particular type and/or version

query Parameters
type
any
Example: type=org.ga4gh:beacon:1.0.0

Filter services/implementations by ServiceType (the standard they implement). Serialized as 'GROUP:ARTIFACT:VERSION'

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create service

Creates a new service with the information specified in requestBody

Authorizations:
BearerAuth
Request Body schema: application/json

new service to create

id
required
string

unique identifier for the implementation/web service in reverse domain name notation

name
required
string

human readable name of the implementation/web service

required
object (ServiceType)

Type of a GA4GH service

description
string

human readable description of the implementation/web service, providing information about how the tool might be used

required
object (OrganizationSummary)
contactUrl
string <uri>

url of the contact for the maintainer/provider of the implementation/web service

documentationUrl
string <uri>

url to the documentation of the implementation/web service (RFC 3986 format). This should help someone learn how to use the implementation/service

createdAt
string <date-time>

timestamp describing when the implementation/web service was first made available (RFC 3339 format)

updatedAt
string <date-time>

timestamp describing when the implementation/web service was last updated (RFC 3339 format)

version
required
string

version of the implementation/web service

environment
string

environment the web service is running in. can be used to distinguish between production, development, and testing/staging environments.

url
required
string <uri>

Base URL of the service (RFC 3986 format).

For REST API services, this is the URL to which all endpoints should be relative. In particular, services implementing GA4GH specifications defined in OAS format (as per the type field) should respond to requests constructed by appending relative paths from the specification to this base URL (e.g. {url}/service-info). See API Server and Base URL for more information on specifying base URLs in OAS 3.

Responses

Request 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",
  • "url": "http://example.com"
}

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",
  • "url": "http://example.com"
}

Get service by id

Show detailed information about a single service

path Parameters
serviceId
any
Example: org.ga4gh.registry

unique identifier for the web 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",
  • "url": "http://example.com"
}

Update service by id

Overwrites the service at the specified id, with the information specified in requestBody

Authorizations:
BearerAuth
path Parameters
serviceId
any
Example: org.ga4gh.registry

unique identifier for the web service

Request Body schema: application/json

new properties for existing service object

id
required
string

unique identifier for the implementation/web service in reverse domain name notation

name
required
string

human readable name of the implementation/web service

required
object (ServiceType)

Type of a GA4GH service

description
string

human readable description of the implementation/web service, providing information about how the tool might be used

required
object (OrganizationSummary)
contactUrl
string <uri>

url of the contact for the maintainer/provider of the implementation/web service

documentationUrl
string <uri>

url to the documentation of the implementation/web service (RFC 3986 format). This should help someone learn how to use the implementation/service

createdAt
string <date-time>

timestamp describing when the implementation/web service was first made available (RFC 3339 format)

updatedAt
string <date-time>

timestamp describing when the implementation/web service was last updated (RFC 3339 format)

version
required
string

version of the implementation/web service

environment
string

environment the web service is running in. can be used to distinguish between production, development, and testing/staging environments.

url
required
string <uri>

Base URL of the service (RFC 3986 format).

For REST API services, this is the URL to which all endpoints should be relative. In particular, services implementing GA4GH specifications defined in OAS format (as per the type field) should respond to requests constructed by appending relative paths from the specification to this base URL (e.g. {url}/service-info). See API Server and Base URL for more information on specifying base URLs in OAS 3.

Responses

Request 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",
  • "url": "http://example.com"
}

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",
  • "url": "http://example.com"
}

Delete service by id

Deletes the service at the specified id

Authorizations:
BearerAuth
path Parameters
serviceId
any
Example: org.ga4gh.registry

unique identifier for the web service

Responses

Response samples

Content type
application/json
{
  • "timestamp": "2020-08-14T19:56:46Z",
  • "status": 404,
  • "error": "Not Found",
  • "message": "the requested resource could not be located",
  • "path": "/v1/services"
}

List service types

Get list of all implemented service types in the registry

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Implementations

/implementations API endpoints are used to retrieve information about implementations (codebases, libraries, tools, etc.) that implement GA4GH standards from the registry. These endpoints can also create, modify, or delete registered implementations

List implementations

Gets list all registered implementations (codebases, libraries, tools) matching filtering criteria. Services may be filtered using the type parameter, which will cause the registry to return implementations relating to particular GA4GH specifications and/or versions

query Parameters
type
any
Example: type=org.ga4gh:beacon:1.0.0

Filter services/implementations by ServiceType (the standard they implement). Serialized as 'GROUP:ARTIFACT:VERSION'

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create implementation

Creates a new implementation with the information specified in requestBody

Authorizations:
BearerAuth
Request Body schema: application/json

new implementation to create

id
required
string

unique identifier for the implementation/web service in reverse domain name notation

name
required
string

human readable name of the implementation/web service

required
object (ServiceType)

Type of a GA4GH service

description
string

human readable description of the implementation/web service, providing information about how the tool might be used

required
object (OrganizationSummary)
contactUrl
string <uri>

url of the contact for the maintainer/provider of the implementation/web service

documentationUrl
string <uri>

url to the documentation of the implementation/web service (RFC 3986 format). This should help someone learn how to use the implementation/service

createdAt
string <date-time>

timestamp describing when the implementation/web service was first made available (RFC 3339 format)

updatedAt
string <date-time>

timestamp describing when the implementation/web service was last updated (RFC 3339 format)

version
required
string

version of the implementation/web service

Responses

Request 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"
}

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"
}

Get implementation by id

Show detailed information about a single implementation

path Parameters
implementationId
any
Example: org.ga4gh.refget.implementation

unique identifier for the implementation (codebase, library, tool, etc.)

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"
}

Update implementation by id

Overwrites the implementation at the specified id, with the information specified in requestBody

Authorizations:
BearerAuth
path Parameters
implementationId
any
Example: org.ga4gh.refget.implementation

unique identifier for the implementation (codebase, library, tool, etc.)

Request Body schema: application/json

new properties for existing implementation object

id
required
string

unique identifier for the implementation/web service in reverse domain name notation

name
required
string

human readable name of the implementation/web service

required
object (ServiceType)

Type of a GA4GH service

description
string

human readable description of the implementation/web service, providing information about how the tool might be used

required
object (OrganizationSummary)
contactUrl
string <uri>

url of the contact for the maintainer/provider of the implementation/web service

documentationUrl
string <uri>

url to the documentation of the implementation/web service (RFC 3986 format). This should help someone learn how to use the implementation/service

createdAt
string <date-time>

timestamp describing when the implementation/web service was first made available (RFC 3339 format)

updatedAt
string <date-time>

timestamp describing when the implementation/web service was last updated (RFC 3339 format)

version
required
string

version of the implementation/web service

Responses

Request 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"
}

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"
}

Delete implementation by id

Deletes the implementation at the specified id

Authorizations:
BearerAuth
path Parameters
implementationId
any
Example: org.ga4gh.refget.implementation

unique identifier for the implementation (codebase, library, tool, etc.)

Responses

Response samples

Content type
application/json
{
  • "timestamp": "2020-08-14T19:56:46Z",
  • "status": 404,
  • "error": "Not Found",
  • "message": "the requested resource could not be located",
  • "path": "/v1/services"
}

Organizations

/organizations API endpoints are used to retrieve information about organizations adopting GA4GH standards, and have registered implementations and/or web services within the registry. These endpoints can also create, modify, or delete implementing organizations from the registry

List organizations

Get list of organizations implementing GA4GH standards, for all services and implementations contained within the registry

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create organization

Creates a new implementing organization with the information specified in requestBody

Authorizations:
BearerAuth
Request Body schema: application/json

new organization to create

id
required
string

unique identifier for this organization

name
required
string

organization full name

shortName
string

organization short name (abbreviation or acronym)

url
required
string

Organization's home page

Array of objects (Service)

list of implementations and services developed/hosted by (or otherwise associated with) the organization

Responses

Request samples

Content type
application/json
{
  • "id": "org.ga4gh",
  • "name": "Global Alliance for Genomics and Health",
  • "shortName": "GA4GH",
  • "url": "https://ga4gh.org",
  • "implementations":
    [
    ]
}

Response samples

Content type
application/json
{
  • "id": "org.ga4gh",
  • "name": "Global Alliance for Genomics and Health",
  • "shortName": "GA4GH",
  • "url": "https://ga4gh.org",
  • "implementations":
    [
    ]
}

Get organization by id

Get all details about a single organization implementing GA4GH standards

path Parameters
organizationId
any
Example: org.ga4gh

unique identifier for the organization

Responses

Response samples

Content type
application/json
{
  • "id": "org.ga4gh",
  • "name": "Global Alliance for Genomics and Health",
  • "shortName": "GA4GH",
  • "url": "https://ga4gh.org",
  • "implementations":
    [
    ]
}

Update organization by id

Overwrites the organization at the specified id, with the information specified in requestBody

Authorizations:
BearerAuth
path Parameters
organizationId
any
Example: org.ga4gh

unique identifier for the organization

Request Body schema: application/json

new properties for existing organization object

id
required
string

unique identifier for this organization

name
required
string

organization full name

shortName
string

organization short name (abbreviation or acronym)

url
required
string

Organization's home page

Array of objects (Service)

list of implementations and services developed/hosted by (or otherwise associated with) the organization

Responses

Request samples

Content type
application/json
{
  • "id": "org.ga4gh",
  • "name": "Global Alliance for Genomics and Health",
  • "shortName": "GA4GH",
  • "url": "https://ga4gh.org",
  • "implementations":
    [
    ]
}

Response samples

Content type
application/json
{
  • "id": "org.ga4gh",
  • "name": "Global Alliance for Genomics and Health",
  • "shortName": "GA4GH",
  • "url": "https://ga4gh.org",
  • "implementations":
    [
    ]
}

Delete organization by id

Deletes the standard at the specified id

Authorizations:
BearerAuth
path Parameters
organizationId
any
Example: org.ga4gh

unique identifier for the organization

Responses

Response samples

Content type
application/json
{
  • "timestamp": "2020-08-14T19:56:46Z",
  • "status": 404,
  • "error": "Not Found",
  • "message": "the requested resource could not be located",
  • "path": "/v1/services"
}