referencemethods.avdl

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

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

/****************  /mode/{mode}  *******************/
/*
See if the server will return fields necessary for interpreting data in the
given mode. If the server supports a mode, it must serve the string "true" at
this URL, and this method will return true on the client side. If the server
does not support a mode, it must return "false".

If the server supports a mode, all fields that that mode requires must be filled
in the server's responses.

Valid modes are currently "classic" and "graph", with the "graph" mode to be
prefered by new client and server implementations.
*/
boolean sendsMode(
  /**
  The mode to ask about.
  */
  string mode) throws GAException;

/****************  /referencesets/search  *******************/
/**
This request maps to the body of `POST /referencesets/search`
as JSON.
*/
record SearchReferenceSetsRequest {
  /**
  If nonempty, return the reference sets which match any of the given
  `md5checksum`s. See `ReferenceSet::md5checksum` for details.
  */
  array<string> md5checksums = [];

  /**
  If nonempty, return reference sets for which the accession
  matches this string. Best to give a version number (e.g. `GCF_000001405.26`).
  If only the main accession number is given then all records with
  that main accession will be returned, whichever version.
  Note that different versions will have different sequences.
  */
  array<string> accessions = [];

  /**
  If not null, return 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 {
  /**
  If not null, return only references which belong to this reference set.
  */
  union { null, string } referenceSetId = null;

  /**
  If nonempty, return only `Reference`s on `Sequence`s with IDs in the list.
  */
  array<string> sequenceIds = [];

  /**
  If nonempty, return references which match any of the given `md5checksums`.
  See `Reference::md5checksum` for details.
  */
  array<string> md5checksums = [];

  /**
  If nonempty, return references for which the accession
  matches this string. Best to give a version number e.g. `GCF_000001405.26`.
  If only the main accession number is given then all records with
  that main accession will be returned, whichever version.
  Note that different versions will have different sequences.
  */
  array<string> accessions = [];

  /**
  If nonempty, return references that have one of the specified names. The name
  specified must match the reference's name exactly, and is case sensitive.
  */
  array<string> referenceNames = [];

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

/******************  /sequences/search  *********************/
/**
This request maps to the body of `POST /sequences/search` as JSON. Specifies a
number of filters, all of which must be satisfied by each result returned.
*/
record SearchSequencesRequest {
  /**
  If not null, return only `Sequence`s that appear in the indicated
  `ReferenceSet`, or any included `ReferenceSet`s.

  If null, `variantSetId` must not be null.
  */
  union { null, string } referenceSetId = null;

  /**
  If not null, return only `Sequence`s that are part of the indicated
  `VariantSet`.

  If null, `referenceSetId` must not be null.
  */
  union { null, string } variantSetId = 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 /sequences/search` expressed as JSON.
*/
record SearchSequencesResponse {
  /**
  The list of matching `Sequence`s.
  */
  array<org.ga4gh.models.Sequence> sequences = [];

  /**
  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 `Sequence`s that match the search criteria.

`POST /sequences/search` must accept a JSON version of `SearchSequencesRequest`
as the post body and will return a JSON version of `SearchSequencesResponse`.
*/
SearchSequencesResponse searchSequences(
  /**
  This request maps to the body of `POST /sequences/search` as
  JSON.
  */
  SearchSequencesRequest request) throws GAException;

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

`GET /sequences/c95d4520-8c63-45f1-924d-6a9604a919fb/bases?start=100&end=200`
*/

/** The response from `GET /sequences/{id}/bases` expressed as JSON. */
record GetSequenceBasesResponse {
  /**
  The offset position (0-based) of the returned string in the sequence. This
  value should match the start request parameter, or be 0.
   */
  long offset = 0;

  /**
  A substring of the sequence requested. Bases are represented as IUPAC-IUB
  codes; this string matches the regexp `[ACGTMRWSYKVHDBN]*`.
  */
  string sequence;
}

/**
Lists bases by sequence ID and optional range. `GET /sequences/{id}/bases`
will return a JSON version of `GetSequenceBasesResponse`. Works for sequences
with associated `Reference`s, as well as novel sequences that come with
`VariantSet`s.
*/
GetSequenceBasesResponse getSequenceBases(
    /** The ID of the sequence. */
    string id,
    /** Additional request parameters to restrict the query. */
    union {null, long} start = null,
    union {null, long} end) throws GAException;

/****************  /joins/search  *******************/
/**
This request maps to the body of `POST /joins/search` as JSON. Specifies a
number of filters, all of which must be satisfied by each result returned.
*/
record SearchJoinsRequest {
  /**
  If not null, return only `Join`s which belong to this reference set, or any
  included `ReferenceSet`s.

  If null, `variantSetId` must not be null.
  */
  union { null, string } referenceSetId = null;

  /**
  If not null, return only `Join`s which belong to this variant set.

  If null, `referenceSetId` must not be null.
  */
  union { null, string } variantSetId = null;

  /**
  If not null, return only `Join`s with at least one `Side` on this sequence.
  sequences.

  If null, `start`, `length`, and `strand` must be null.
  */
  union { null, string } sequenceId = null;

  /**
  If not null, return only `Join`s with at least one `Side` at this index or
  later in the `Sequence` specified by `sequenceId`.

  If null, `length` must be null.
  */

  union { null, long } start = null;

  /**
  If not null, return only `Join`s with at least one `Side` on the sequence
  specified by `sequenceId` in the interval [`start`, `start` + `length`).
  */
  union { null, long } length = null;

  /**
  If not null, return only `Join`s which join onto this strand of the `Sequence`
  specified by `sequenceId`.
  */
  union { null, org.ga4gh.models.Strand } strand = 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 /joins/search` expressed as JSON.
*/
record SearchJoinsResponse {
  /** The list of matching joins. */
  array<org.ga4gh.models.Join> joins = [];

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

`POST /joins/search` must accept a JSON version of
`SearchJoinsRequest` as the post body and will return a JSON
version of `SearchJoinsResponse`.
*/
SearchJoinsResponse searchJoins(
  /**
  This request maps to the body of `POST /joins/search`
  as JSON.
  */
  SearchJoinsRequest request) throws GAException;


/****************  /subgraph/segments  *******************/
/**
This request maps to the body of `POST /subgraph/sequences` as JSON. Specifies
a`Position` and a radius (in bases), and requests all `Segment`s reachable
within that number of bases from that position.

Starting at the specified `Position`, and with a 0 radius denoting only that
`Position`, walk outwards this many bases along all possible paths, traversing
`Join`s only if necessary. All `Segment`s covering all bases visited during this
walk should be returned.
*/
record ExtractSubgraphSegmentsRequest {

  /**
  If not null, return only `Segment`s of `Sequence`s which belong to this
  reference set, or any included `ReferenceSet`s.

  If null, `variantSetId` must not be null.
  */
  union { null, string } referenceSetId = null;

  /**
  If not null, return only `Segment`s of `Sequence`s which belong to this
  variant set.

  If null, `referenceSetId` must not be null.
  */
  union { null, string } variantSetId = null;

  /**
  Base around which the subgraph is to be extracted.
  */
  org.ga4gh.models.Position position;

  /**
  Distance from the `position` to walk along all possible paths, when looking
  for bases to include in the returned subgraph.
  */
  long radius;

  /**
  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 /subgraph/segments` expressed as JSON.
*/
record ExtractSubgraphSegmentsResponse {
  /**
  The list of `Segment`s in the subgraph. `Segment`s are returned in arbitrary
  order, and multiple `Segment`s may abut, but each is returned only once and no
  two may overlap.
  */
  array<org.ga4gh.models.Segment> segments = [];

  /**
  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 `Segment`s defining the subgraph reachable within a certain
radius of a certain `Position`.

`POST /subgraph/segments` must accept a JSON version of
`ExtractSubgraphSegmentsRequest` as the post body and will return a JSON
version of `ExtractSubgraphSegmentsResponse`.
*/
ExtractSubgraphSegmentsResponse extractSubgraphSegments(
  /**
  This request maps to the body of `POST /subgraph/segments`
  as JSON.
  */
  ExtractSubgraphSegmentsRequest request) throws GAException;

/****************  /subgraph/joins  *******************/
/**
This request maps to the body of `POST /subgraph/joins` as JSON. Specifies
a`Position` and a radius (in bases), and requests all `Join`s reachable
within that number of bases from that position.

Starting at the specified `Position`, and with a 0 radius denoting only that
`Position`, walk outwards this many bases along all possible paths, traversing
`Join`s only if necessary. All `Join`s traversed during this walk should be
returned.
*/
record ExtractSubgraphJoinsRequest {

  /**
  If not null, return only `Join`s which belong to this
  reference set, or any included `ReferenceSet`s.

  If null, `variantSetId` must not be null.
  */
  union { null, string } referenceSetId = null;

  /**
  If not null, return only `Join`s which belong to this variant set.

  If null, `referenceSetId` must not be null.
  */
  union { null, string } variantSetId = null;

  /**
  Base around which the subgraph is to be extracted.
  */
  org.ga4gh.models.Position position;

  /**
  Distance from the `position` to walk along all possible paths, when looking
  for `Join`s to include in the returned subgraph.
  */
  long radius;

  /**
  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 /subgraph/joins` expressed as JSON.
*/
record ExtractSubgraphJoinsResponse {
  /**
  The list of `Join`s in the subgraph. `Join`s are returned in arbitrary
  order, but each `Join` will be returned only once.
  */
  array<org.ga4gh.models.Join> joins = [];

  /**
  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 `Join`s defining the subgraph reachable within a certain
radius of a certain `Position`.

`POST /subgraph/joins` must accept a JSON version of
`ExtractSubgraphJoinsRequest` as the post body and will return a JSON
version of `ExtractSubgraphJoinsResponse`.
*/
ExtractSubgraphJoinsResponse extractSubgraphJoins(
  /**
  This request maps to the body of `POST /subgraph/joins`
  as JSON.
  */
  ExtractSubgraphJoinsRequest request) throws GAException;

}