variantmethods.avdl

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

import idl "methods.avdl";
import idl "variants.avdl";

/******************  /variantsets/search  *********************/
/** This request maps to the body of `POST /variantsets/search` as JSON. */
record SearchVariantSetsRequest {
  /**
  The `Dataset` to search.
  */
  string datasetId;

  /**
  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 SearchVariantSetsResponse {
  /** The list of matching variant sets. */
  array<org.ga4gh.models.VariantSet> 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 `VariantSet` matching the search criteria.

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

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

/******************  /variants/search  *********************/
/** This request maps to the body of `POST /variants/search` as JSON. */
record SearchVariantsRequest {
  /**
  The `VariantSet` to search.
  */
  string variantSetId;

  /**
  Only return variant calls which belong to call sets with these IDs.
  If an empty array, returns variants without any call objects.
  If null, returns all variant calls.
  */
  union { null, array<string> } callSetIds = null;

  /** 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 SearchVariantsResponse {
  /**
  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 `VariantSet` is guaranteed to match the ordering
  of the calls on each `Variant`. The number of results will also be
  the same.
  */
  array<org.ga4gh.models.Variant> 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 `Variant` matching the search criteria.

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

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

/******************  /callsets/search  *********************/
/** This request maps to the body of `POST /callsets/search` as JSON. */
record SearchCallSetsRequest {
  /**
  The VariantSet to search.
  */
  string variantSetId;

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

  // TODO: Add more ways to search by other metadata

  /**
  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 SearchCallSetsResponse {
  /** The list of matching call sets. */
  array<org.ga4gh.models.CallSet> 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 `CallSet` matching the search criteria.

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

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

}