htsget: specify how to request unmapped (unplaced) reads

htsget.md

@@ -4,7 +4,7 @@ title: htsget protocol
 suppress_footer: true
 ---
 
-# Htsget retrieval API spec v1.1.0
+# Htsget retrieval API spec v1.1.1
 
 # Design principles
 
@@ -165,7 +165,9 @@ The server SHOULD reply with an `UnsupportedFormat` error if the requested forma
 `referenceName` 
 _optional_
 </td><td>
-The reference sequence name, for example "chr1", "1", or "chrX". If unspecified, all reads (mapped and unmapped) are returned. [^b]
+The reference sequence name, for example "chr1", "1", or "chrX". If unspecified, all records are returned regardless of position.
+
+For the reads endpoint: if "\*", unplaced unmapped reads are returned. If unspecified, all reads (mapped and unmapped) are returned. (*Unplaced unmapped* reads are the subset of unmapped reads completely without location information, i.e., with RNAME and POS field values of "\*" and 0 respectively. See the [SAM specification](http://samtools.github.io/hts-specs/SAMv1.pdf) for details of placed and unplaced unmapped reads.)
 
 The server SHOULD reply with a `NotFound` error if the requested reference does not exist.
 </td></tr>
@@ -175,7 +177,7 @@ _optional 32-bit unsigned integer_
 </td><td>
 The start position of the range on the reference, 0-based, inclusive. 
 
-The server SHOULD respond with an `InvalidInput` error if `start` is specified and a reference is not specified (see `referenceName`).
+The server SHOULD respond with an `InvalidInput` error if `start` is specified and either no reference is specified or `referenceName` is "\*".
 
 The server SHOULD respond with an `InvalidRange` error if `start` and `end` are specified and `start` is greater than `end`.
 </td></tr>
@@ -185,7 +187,7 @@ _optional 32-bit unsigned integer_
 </td><td>
 The end position of the range on the reference, 0-based exclusive.
 
-The server SHOULD respond with an `InvalidInput` error if `end` is specified and a reference is not specified (see `referenceName`).
+The server SHOULD respond with an `InvalidInput` error if `end` is specified and either no reference is specified or `referenceName` is "\*".
 
 The server SHOULD respond with an `InvalidRange` error if `start` and `end` are specified and `start` is greater than `end`.
 </td></tr>
@@ -378,7 +380,6 @@ The data block URL and headers might contain embedded authentication tokens; the
 * add a mechanism to request reads from more than one ID at a time (e.g. for a trio)
 * allow clients to provide a suggested data block size to the server
 * add POST support (if and when request sizes get large)
-* [mlin] add a way to request all unmapped reads (e.g. by passing `*` for `referenceName`)
 * [dglazer] add a way to request reads in GA4GH binary format [^d] (e.g. fmt=proto)
 
 ## Existing clarification suggestions