read_service

************** /readgroupsets *****************/

SearchReads(request)
Parameters:requestSearchReadsRequest
Return type:SearchReadsResponse
Throws:GAException

Gets a list of ReadAlignment s for one or more ReadGroup s.

searchReads operates over a genomic coordinate space of reference sequence and position defined by the Reference s to which the requested ReadGroup s are aligned.

If a target positional range is specified, search returns all reads whose alignment to the reference genome overlap the range. A query which specifies only read group IDs yields all reads in those read groups, including unmapped reads.

All reads returned (including reads on subsequent pages) are ordered by genomic coordinate (by reference sequence, then position). Reads with equivalent genomic coordinates are returned in an unspecified order. This order must be consistent for a given repository, such that two queries for the same content (regardless of page size) yield reads in the same order across their respective streams of paginated responses.

POST /reads/search must accept a JSON version of SearchReadsRequest as the post body and will return a JSON version of SearchReadsResponse.

SearchReadGroupSets(request)
Parameters:requestSearchReadGroupSetsRequest
Return type:SearchReadGroupSetsResponse
Throws:GAException

Gets a list of ReadGroupSet matching the search criteria.

POST /readgroupsets/search must accept a JSON version of SearchReadGroupSetsRequest as the post body and will return a JSON version of SearchReadGroupSetsResponse . Only readgroups that match an optionally supplied biosampleId will be included in the response.

GetReadGroupSet(request)
Parameters:requestGetReadGroupSetRequest
Return type:ReadGroupSet
Throws:GAException

Gets a ReadGroupSet by ID.

GET /readgroupsets/{read_group_set_id} will return a JSON version of ReadGroupSet.

message SearchReadGroupSetsRequest
Fields:
  • dataset_id (string) – The dataset to search.
  • name (string) – Only return read group sets with this name (case-sensitive, exact match).
  • biosample_id (string) – Specifying the id of a Biosample record will return only readgroups with the given biosampleId.
  • page_size (integer) – Specifies the maximum number of results to return in a single page. If unspecified, a system default will be used.
  • page_token (string) – 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 next_page_token from the previous response.

This request maps to the body of POST /readgroupsets/search as JSON.

TODO: Factor this out to a common API patterns section. - If searching by a resource ID, and that resource is not found, the method will return a 404 HTTP status code (NOT_FOUND). - If searching by other attributes, e.g. name, and no matches are found, the method will return a 200 HTTP status code (OK) with an empty result list.

message SearchReadGroupSetsResponse
Fields:
  • read_group_sets (list of ReadGroupSet) – The list of matching read group sets.
  • next_page_token (string) – 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.

This is the response from POST /readgroupsets/search expressed as JSON.

message GetReadGroupSetRequest
Fields:
  • read_group_set_id (string) – The ID of the ReadGroupSet to be retrieved.

This request maps to the URL GET /readgroupsets/{read_group_set_id}.

message SearchReadsRequest
Fields:
  • read_group_ids (string) – The ReadGroups to search. At least one id must be specified.
  • reference_id (string) – The reference to query. Leaving blank returns results from all references, including unmapped reads - this could be very large.
  • start (long) – The start position (0-based) of this query. If a reference is specified, this 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).
  • end (long) – The end position (0-based, exclusive) of this query. If a reference is specified, this defaults to the reference’s length.
  • page_size (integer) – Specifies the maximum number of results to return in a single page. If unspecified, a system default will be used.
  • page_token (string) – 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 next_page_token from the previous response.

************** /reads ***************** This request maps to the body of POST /reads/search as JSON.

If a reference is specified, all queried ReadGroup`s must be aligned to `ReferenceSet`s containing that same `Reference. If no reference is specified, all ReadGroup`s must be aligned to the same `ReferenceSet.

message SearchReadsResponse
Fields:
  • alignments (list of ReadAlignment) – The list of matching alignment messages, sorted by position. Unmapped reads, which have no position, are returned last.
  • next_page_token (string) – 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.

This is the response from POST /reads/search expressed as JSON.