variantmethods.avdl

@namespace("org.ga4gh")
protocol GAVariantMethods {

import idl "variants.avdl";

/******************  /variantsets/search  *********************/
/** This request maps to the body of `POST /variantsets/search` as JSON. */
record GASearchVariantSetsRequest {
  /**
    If specified, will restrict the query to variant sets within the
    given datasets.
  */
  array<string> datasetIds = [];

  /**
    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 /variantsets/search` expressed as JSON. */
record GASearchVariantSetsResponse {
  /** The list of matching variant sets. */
  array<GAVariantSet> variantSets = [];

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

  `POST /variantsets/search` must accept a JSON version of
  `GASearchVariantSetsRequest` as the post body and will return a JSON version
  of `GASearchVariantSetsResponse`.
*/
GASearchVariantSetsResponse searchVariantSets(
    /** This request maps to the body of `POST /variantsets/search` as JSON. */
    GASearchVariantSetsRequest request) throws GAException;

/******************  /variants/search  *********************/
/** This request maps to the body of `POST /variants/search` as JSON. */
record GASearchVariantsRequest {
  /** Required. The IDs of the variant sets to search over. */
  array<string> variantSetIds = [];

  /** Only return variants which have exactly this name. */
  union { null, string } variantName = null;

  /**
  Only return variant calls which belong to call sets with these IDs.
  Leaving this blank returns all variant calls.
  */
  array<string> callSetIds = [];

  /** Required. Only return variants on this reference. */
  string referenceName;

  /**
  Required. The beginning of the window (0-based, inclusive) for
  which overlapping variants should be returned.
  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;

  /**
  Required. The end of the window (0-based, exclusive) for which overlapping
  variants should be returned.
  */
  long end;

  /**
  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 /variants/search` expressed as JSON. */
record GASearchVariantsResponse {
  /**
  The list of matching variants.
  If the `callSetId` field on the returned calls is not present,
  the ordering of the call sets from a `SearchCallSetsRequest`
  over the parent `GAVariantSet` is guaranteed to match the ordering
  of the calls on each `GAVariant`. The number of results will also be
  the same.
  */
  array<GAVariant> variants = [];

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

`POST /variants/search` must accept a JSON version of `GASearchVariantsRequest`
as the post body and will return a JSON version of `GASearchVariantsResponse`.
*/
GASearchVariantsResponse searchVariants(
    /** This request maps to the body of `POST /variants/search` as JSON. */
    GASearchVariantsRequest request) throws GAException;

/******************  /callsets/search  *********************/
/** This request maps to the body of `POST /callsets/search` as JSON. */
record GASearchCallSetsRequest {
  /**
  If specified, will restrict the query to call sets within the
  given variant sets.
  */
  array<string> variantSetIds = [];

  /**
  Only return call sets for which a substring of the name matches this
  string.
  */
  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 /callsets/search` expressed as JSON. */
record GASearchCallSetsResponse {
  /** The list of matching call sets. */
  array<GACallSet> callSets = [];

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

`POST /callsets/search` must accept a JSON version of `GASearchCallSetsRequest`
as the post body and will return a JSON version of `GASearchCallSetsResponse`.
*/
GASearchCallSetsResponse searchCallSets(
    /** This request maps to the body of `POST /callsets/search` as JSON. */
    GASearchCallSetsRequest request) throws GAException;
}