referencemethods.avdl

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

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

/****************  /referencesets/search  *******************/
/**
This request maps to the body of `POST /referencesets/search`
as JSON.
*/
record SearchReferenceSetsRequest {
  /**
  If not null, return the reference sets for which the
  `md5checksum` matches this string (case-sensitive, exact match).
  See `ReferenceSet::md5checksum` for details.
  */
  union { null, string } md5checksum = null;

  /**
  If not null, return the reference sets for which the `accession`
  matches this string (case-sensitive, exact match).
  */
  union { null, string } accession = null;

  /**
  If not null, return the reference sets for which the `assemblyId`
  matches this string (case-sensitive, exact match).
  */
  union { null, string } assemblyId = 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 /referencesets/search`
expressed as JSON.
*/
record SearchReferenceSetsResponse {
  /** The list of matching reference sets. */
  array<org.ga4gh.models.ReferenceSet> referenceSets = [];

  /**
  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 `ReferenceSet` matching the search criteria.

`POST /referencesets/search` must accept a JSON version of
`SearchReferenceSetsRequest` as the post body and will return a JSON
version of `SearchReferenceSetsResponse`.
*/
SearchReferenceSetsResponse searchReferenceSets(
  /**
  This request maps to the body of `POST /referencesets/search`
  as JSON.
  */
  SearchReferenceSetsRequest request) throws GAException;

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

/****************  /references/search  *******************/
/**
This request maps to the body of `POST /references/search`
as JSON.
*/
record SearchReferencesRequest {
  /**
  The `ReferenceSet` to search.
  */
  string referenceSetId;

  /**
  If not null, return the references for which the
  `md5checksum` matches this string (case-sensitive, exact match).
  See `ReferenceSet::md5checksum` for details.
  */
  union { null, string } md5checksum = null;

  /**
  If not null, return the references for which the `accession`
  matches this string (case-sensitive, exact match).
  */
  union { null, string } accession = 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 /references/search` expressed as JSON.
*/
record SearchReferencesResponse {
  /** The list of matching references. */
  array<org.ga4gh.models.Reference> references = [];

  /**
  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 `Reference` matching the search criteria.

`POST /references/search` must accept a JSON version of
`SearchReferencesRequest` as the post body and will return a JSON
version of `SearchReferencesResponse`.
*/
SearchReferencesResponse searchReferences(
  /**
  This request maps to the body of `POST /references/search`
  as JSON.
  */
  SearchReferencesRequest request) throws GAException;

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

/****************  /references/{id}/bases  *******************/
/**
The query parameters for a request to `GET /references/{id}/bases`, for
example:

`GET /references/{id}/bases?start=100&end=200`
*/
record ListReferenceBasesRequest {
  /**
  The start position (0-based) of this query. 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).
  */
  long start = 0;

  /**
  The end position (0-based, exclusive) of this query. Defaults
  to the length of this `Reference`.
  */
  union { null, long } end = 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;
}

/** The response from `GET /references/{id}/bases` expressed as JSON. */
record ListReferenceBasesResponse {
  /**
  The offset position (0-based) of the given sequence from the start of this
  `Reference`. This value will differ for each page in a paginated request.
   */
  long offset = 0;

  /**
  A substring of the bases that make up this reference. Bases are represented
  as IUPAC-IUB codes; this string matches the regexp `[ACGTMRWSYKVHDBN]*`.
  */
  string sequence;

  /**
  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;
}

/**
Lists `Reference` bases by ID and optional range.
`GET /references/{id}/bases` will return a JSON version of
`ListReferenceBasesResponse`.
*/
ListReferenceBasesResponse getReferenceBases(
  /** The ID of the `Reference`. */
  string id,
  /** Additional request parameters to restrict the query. */
  ListReferenceBasesRequest request) throws GAException;

}