readmethods.avdl

@namespace("org.ga4gh.methods")
protocol ReadMethods {

import idl "common.avdl";
import idl "methods.avdl";
import idl "reads.avdl";

/******************  /reads/search  *********************/
/**
This request maps to the body of `POST /reads/search` as JSON.

If a reference is specified, all queried `ReadGroup`s must be aligned
to `ReferenceSet`s containing that same `Reference`. If no reference is
specified, all `ReadGroup`s must be aligned to the same `ReferenceSet`.
*/
record SearchReadsRequest {
  /**
  The ReadGroups to search. At least one readGroupId must be specified.
  */
  array<string> readGroupIds;

  /**
  The reference to query. Leaving blank returns results from all
  references, including unmapped reads - this could be very large.
  */
  union { null, string } referenceId = null;

  /**
  The start position (0-based) of this query.
  If a reference is specified, this defaults to 0.
  Genomic positions are non-negative integers less than reference length.
  Requests spanning the join of circular genomes are represented as
  two requests one on each side of the join (position 0).
  */
  union { null, long } start = null;

  /**
  The end position (0-based, exclusive) of this query.
  If a reference is specified, this defaults to the
  reference's length.
  */
  union { null, long } end = null;

  /**
  Specifies the maximum number of results to return in a single page.
  If unspecified, a system default will be used.
  */
  union { null, int } pageSize = null;

  /**
  The continuation token, which is used to page through large result sets.
  To get the next page of results, set this parameter to the value of
  `nextPageToken` from the previous response.
  */
  union { null, string } pageToken = null;
}

/** This is the response from `POST /reads/search` expressed as JSON. */
record SearchReadsResponse {
  /**
  The list of matching alignment records, sorted by position.
  Unmapped reads, which have no position, are returned last.
  */
  array<org.ga4gh.models.ReadAlignment> alignments = [];

  /**
  The continuation token, which is used to page through large result sets.
  Provide this value in a subsequent request to return the next page of
  results. This field will be empty if there aren't any additional results.
  */
  union { null, string } nextPageToken = null;
}

/**
Gets a list of `ReadAlignment` matching the search criteria.

`POST /reads/search` must accept a JSON version of `SearchReadsRequest` as
the post body and will return a JSON version of `SearchReadsResponse`.
*/
SearchReadsResponse searchReads(
  /** This request maps to the body of `POST /reads/search` as JSON. */
  SearchReadsRequest request) throws GAException;

/******************  /readgroupsets/search  *********************/
/** This request maps to the body of `POST /readgroupsets/search` as JSON. */
record SearchReadGroupSetsRequest {
  /**
  The dataset to search.
  */
  string datasetId;

  /**
  Only return read group sets with this name (case-sensitive, exact match).
  */
  union { null, string } name = null;

  /**
  Specifies the maximum number of results to return in a single page.
  If unspecified, a system default will be used.
  */
  union { null, int } pageSize = null;

  /**
  The continuation token, which is used to page through large result sets.
  To get the next page of results, set this parameter to the value of
  `nextPageToken` from the previous response.
  */
  union { null, string } pageToken = null;
}

/** This is the response from `POST /readgroupsets/search` expressed as JSON. */
record SearchReadGroupSetsResponse {
  /** The list of matching read group sets. */
  array<org.ga4gh.models.ReadGroupSet> readGroupSets = [];

  /**
  The continuation token, which is used to page through large result sets.
  Provide this value in a subsequent request to return the next page of
  results. This field will be empty if there aren't any additional results.
  */
  union { null, string } nextPageToken = null;
}

/**
Gets a list of `ReadGroupSet` matching the search criteria.

`POST /readgroupsets/search` must accept a JSON version of
`SearchReadGroupSetsRequest` as the post body and will return a JSON
version of `SearchReadGroupSetsResponse`.
*/
SearchReadGroupSetsResponse searchReadGroupSets(
  /**
  This request maps to the body of `POST /readgroupsets/search` as JSON.
  */
  SearchReadGroupSetsRequest request) throws GAException;

/****************  /readgroupsets/{id}  *******************/
/**
Gets a `org.ga4gh.models.ReadGroupSet` by ID.
`GET /readgroupsets/{id}` will return a JSON version of `ReadGroupSet`.
*/
org.ga4gh.models.ReadGroupSet getReadGroupSet(
  /**
  The ID of the `ReadGroupSet`.
  */
  string id) throws GAException;

/****************  /readgroups/{id}  *******************/
/**
Gets a `org.ga4gh.models.ReadGroup` by ID.
`GET /readgroups/{id}` will return a JSON version of `ReadGroup`.
*/
org.ga4gh.models.ReadGroup getReadGroup(
  /**
  The ID of the `ReadGroup`.
  */
  string id) throws GAException;

/******************  /datasets/search  *********************/
/**
This request maps to the body of `POST /datasets/search` as JSON.
*/
record SearchDatasetsRequest {

  /**
  Specifies the maximum number of results to return in a single page.
  If unspecified, a system default will be used.
  */
  union { null, int } pageSize = null;

  /**
  The continuation token, which is used to page through large result sets.
  To get the next page of results, set this parameter to the value of
  `nextPageToken` from the previous response.
  */
  union { null, string } pageToken = null;
}

/**
This is the response from `POST /datasets/search` expressed as JSON.
*/
record SearchDatasetsResponse {
  /** The list of datasets. */
  array<org.ga4gh.models.Dataset> datasets = [];

  /**
  The continuation token, which is used to page through large result sets.
  Provide this value in a subsequent request to return the next page of
  results. This field will be empty if there aren't any additional results.
  */
  union { null, string } nextPageToken = null;
}

/**
Gets a list of datasets accessible through the API.

TODO: Reads and variants both want to have datasets. Are they the same object?

`POST /datasets/search` must accept a JSON version of
`SearchDatasetsRequest` as the post body and will return a JSON version
of `SearchDatasetsResponse`.
*/
SearchDatasetsResponse searchDatasets(
  /**
  This request maps to the body of `POST /datasets/search` as JSON.
  */
  SearchDatasetsRequest request) throws GAException;

/****************  /datasets/{id}  *******************/
/**
Gets a `Dataset` by ID.
`GET /datasets/{id}` will return a JSON version of `Dataset`.
*/
org.ga4gh.models.Dataset getDataset(
  /**
  The ID of the `Dataset`.
  */
  string id) throws GAException;

}