Get info about a DrsObject

GET

/objects/{object_id}

const url = 'https://your-candig-domain/drs/ga4gh/drs/v1/objects/example?expand=false';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://your-candig-domain/drs/ga4gh/drs/v1/objects/example?expand=false'

Returns object metadata, and a list of access methods that can be used to fetch object bytes.

Authorizations

None
BasicAuth
BearerAuth

Parameters

Path Parameters

object_id

required

string format: path

DrsObject identifier

Query Parameters

expand

boolean

If false and the object_id refers to a bundle, then the ContentsObject array contains only those objects directly contained in the bundle. That is, if the bundle contains other bundles, those other bundles are not recursively included in the result. If true and the object_id refers to a bundle, then the entire set of objects in the bundle is expanded. That is, if the bundle contains aother bundles, then those other bundles are recursively expanded and included in the result. Recursion continues through the entire sub-tree of the bundle. If the object_id refers to a blob, then the query parameter is ignored.

Example

false

Responses

200

The DrsObject was found successfully

application/json

One of:

A DrsObject that describes the sequencing experiment.

object

name

required

The biosample identifier for the experiment.

string

required

A unique ID for the experiment. Often the alias for the experiment, as defined by the sequencing center

string

contents

required

The specific analysis contents objects that were generated from this experiment.

Array<object>

object

name

required

The identifier of the linked DRS object

string

required

Alternate identifier for the linked DRS object

string

drs_uri

required

The DRS uri(s) to the linked DrsObject

Array<string>

description

required

The library strategy used in this experiment

string

Allowed values: wgs wts

program

required

The program this object was ingested as part of

string

metadata

Metadata about the experiment (see Experiment in ingest_openapi.yaml)

object

aliases

A list of strings that can be used to find other metadata about this DrsObject from external metadata sources. These aliases can be used to represent secondary accession numbers or external GUIDs.

Array<string>

self_uri

A drs:// hostname-based URI, as defined in the DRS documentation, that tells clients how to access this object. The intent of this field is to make DRS objects self-contained, and therefore easier for clients to store and pass around. For example, if you arrive at this DRS JSON by resolving a compact identifier-based DRS URI, the self_uri presents you with a hostname and properly encoded DRS ID for use in subsequent access endpoint calls.

string

size

The cumulative size, in bytes, of items in the contents field.

integer format: int64

created_time

Timestamp of content creation in RFC3339. (This is the creation time of the underlying content, not of the JSON object.)

string format: date-time

updated_time

Timestamp of content update in RFC3339, identical to created_time in systems that do not support updates. (This is the update time of the underlying content, not of the JSON object.)

string format: date-time

version

A string representing a version. (Some systems may use checksum, a RFC3339 timestamp, or an incrementing version number.)

string

checksums

Array<object>

object

checksum

required

The hex-string encoded checksum for the data

string

type

required

The digest method used to create the checksum. The value (e.g. sha-256) SHOULD be listed as Hash Name String in the https://www.iana.org/assignments/named-information/named-information.xhtml#hash-alg[IANA Named Information Hash Algorithm Registry]. Other values MAY be used, as long as implementors are aware of the issues discussed in https://tools.ietf.org/html/rfc6920#section-9.4[RFC6920]. GA4GH may provide more explicit guidance for use of non-IANA-registered algorithms in the future. Until then, if implementors do choose such an algorithm (e.g. because it’s implemented by their storage provider), they SHOULD use an existing standard type value such as md5, etag, crc32c, trunc512, or sha1.

string

A DrsObject that describes the raw read files.

object

name

required

The experiment’s name that this run is generated from.

string

required

The unique ID for the run.

string

contents

required

The specific raw FASTQ files that were generated in this Run.

Array<object>

object

name

required

The identifier of the linked DRS object

string

required

Alternate identifier for the linked DRS object

string

drs_uri

required

The DRS uri(s) to the linked DrsObject

Array<string>

description

required

For a Run object, the description should be raw_reads

string

Allowed values: raw_reads

program

required

The program this object was ingested as part of

string

self_uri

string

aliases

A list of strings that can be used to find other metadata about this DrsObject from external metadata sources. These aliases can be used to represent secondary accession numbers or external GUIDs.

Array<string>

metadata

Metadata about the run (see Run in ingest_openapi.yaml)

object

size

The cumulative size, in bytes, of items in the contents field.

integer format: int64

created_time

Timestamp of content creation in RFC3339. (This is the creation time of the underlying content, not of the JSON object.)

string format: date-time

updated_time

Timestamp of content update in RFC3339, identical to created_time in systems that do not support updates. (This is the update time of the underlying content, not of the JSON object.)

string format: date-time

version

A string representing a version. (Some systems may use checksum, a RFC3339 timestamp, or an incrementing version number.)

string

checksums

Array<object>

object

checksum

required

The hex-string encoded checksum for the data

string

type

required

string

A DrsObject that describes a sequencing analysis. It usually will consist of a data file, e.g. a variant or read file, and its associated index file. Its contents should also include any associated Experiments (as ContentObjects), ordered in order of appearance in the associated variant/read files.

object

name

required

The unique ID for this analysis

string

required

Same as name

string

contents

required

The specific analysis contents objects that comprise this analysis DRS entity. Should contain one or more ContentsObjects that describe the data files in the analysis, and one or more ContentsObjects corresponding to the experiments analyzed in the analysis.

Array<object>

>= 1 items

object

name

required

The identifier of the linked DRS object

string

required

Alternate identifier for the linked DRS object

string

drs_uri

required

The DRS uri(s) to the linked DrsObject

Array<string>

description

required

Type of sequencing analysis

string

Allowed values: reference_alignment sequence_variation sequence_annotation

program

required

The program this object was ingested as part of

string

reference_genome

required

The reference genome used to compile this analysis

string

Allowed values: hg37 hg38

indexed

1 if the object has been indexed for search, 0 if not

integer

aliases

A list of strings that can be used to find other metadata about this DrsObject from external metadata sources. These aliases can be used to represent secondary accession numbers or external GUIDs.

Array<string>

self_uri

string

size

The cumulative size, in bytes, of items in the contents field.

integer format: int64

created_time

Timestamp of content creation in RFC3339. (This is the creation time of the underlying content, not of the JSON object.)

string format: date-time

updated_time

Timestamp of content update in RFC3339, identical to created_time in systems that do not support updates. (This is the update time of the underlying content, not of the JSON object.)

string format: date-time

version

A string representing a version. (Some systems may use checksum, a RFC3339 timestamp, or an incrementing version number.)

string

checksums

Array<object>

object

checksum

required

The hex-string encoded checksum for the data

string

type

required

string

metadata

Metadata about the analysis (see Analysis in ingest_openapi.yaml)

object

A DrsObject that describes a data file, e.g. a variant or read file.

object

name

required

The filename for this data file, including its file extensions.

string

required

The filename for this data file, including its file extensions.

string

description

required

Type of file

string

access_methods

required

The list of access methods that can be used to fetch the DrsObject.

Array

>= 1 items

Any of:

object
object

A full URL describing the file’s location

object

type

required

string

Allowed values: file download

access_url

required

object

url

required

string

headers

Array<string>

program

required

The program this object was ingested as part of

string

Example

{
  "description": "wgs",
  "self_uri": "drs://drs.example.org/314159",
  "checksums": [
    {
      "type": "sha-256"
    }
  ]
}