sequenceAnnotationmethods.avdl

@namespace("org.ga4gh.methods")

protocol SequenceAnnotationMethods {

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

  // FIXME: wiggle methods not defined.

  /******************  /features/search  *********************/

  /**
  This request maps to the body of `POST /features/search` as JSON.
  */
  record SearchFeaturesRequest {
    /**
    The annotation set to search within. Either `featureSetId` or
    `parentId` must be non-empty.
    */
    union { null, string } featureSetId;

    /**
    Restricts the search to direct children of the given parent `feature`
    ID. Either `featureSetId` or `parentId` must be non-empty.
    */
    union { null, string } parentId;

    /**
    If specified, this query matches only annotations which overlap this path.
    */
    union { null, org.ga4gh.models.Path } range = null;

    // TODO: Fix this field. Clarify semantics around how OntologyTerm matching works, or
    // change the Ontology term field on the feature.
    /**
    If specified, this query matches only annotations which match one of the
    provided feature types.
    */
    array<org.ga4gh.models.OntologyTerm> features = [];

    /**
    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 /features/search` expressed as JSON. */
  record SearchFeaturesResponse {
    /**
    The list of matching annotations, sorted by start position. Annotations which
    share a start position are returned in a deterministic order.
    */
    array<org.ga4gh.models.Feature> features = [];

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

  `POST /features/search` must accept a JSON version of
  `SearchFeaturesRequest` as the post body and will return a JSON version of
  `SearchFeaturesResponse`.
  */
  SearchFeaturesResponse searchFeatures(
    /** This request maps to the body of `POST /features/search` as JSON. */
    SearchFeaturesRequest request) throws GAException;


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

}

// TODO: AnnotationSet methods.