From 5358ff0ecc846beebc2ecacb3b394ba6b39042e5 Mon Sep 17 00:00:00 2001 From: Jerome Kelleher Date: Sun, 13 May 2018 15:29:04 +0100 Subject: [PATCH] Header and data boolean flags for htsget. --- htsget.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/htsget.md b/htsget.md index a536c2eb0..9971f656b 100644 --- a/htsget.md +++ b/htsget.md @@ -41,6 +41,14 @@ JSON responses SHOULD include a `Content-Type` header describing the htsget prot Content-Type: application/vnd.ga4gh.htsget.v1.0.0+json; charset=utf-8 +## Data format assumptions + +The protocol is agnostic to the specific details of the data formats that can be exchanged. However, a few key underlying assumptions are made: + +1. Queries over a genomic range `(referenceName, start, end)` can be mapped to a contiguous block of bytes interpretable by clients; + +2. The data format is composed of `headers` and `data` sections. The `headers` section contains metadata pertaining to the information encoded in the `data` section and is at the beginning of byte stream. Ordinarily both the `headers` and `data` sections of the stream are required for it to be well-formed, but there are situations in which a client may wish to retrieve either in isolation (see below). + ## Errors The server MUST respond with an appropriate HTTP status code (4xx or 5xx) when an error condition is detected. In the case of transient server errors, (e.g., 503 and other 5xx status codes), the client SHOULD implement appropriate retry logic as discussed in [Reliability & performance considerations](#reliability--performance-considerations) below. @@ -190,6 +198,12 @@ The server SHOULD respond with an `InvalidInput` error if `end` is specified and The server SHOULD respond with an `InvalidRange` error if `start` and `end` are specified and `start` is greater than `end`. +`headers_only` +_optional_ integer (boolean) + +If 1, only return data-format specific metadata headers in the returned data stream and not the data content. If 0, include both these headers and body data (the default). The server SHOULD respond if an `InvalidInput` error if any other values are provided. Default: 0 + + `fields` _optional_ @@ -234,6 +248,12 @@ QUAL | Base quality scores Example: `fields=QNAME,FLAG,POS`. +### Format headers and data + +Clients may wish to retrieve either the headers or data sections of the requested byte stream in isolation. For example, a client may wish to first fetch the header of a BAM stream to interrogate its metadata before performing other queries. Or, a client may already have the headers for a particular VCF file and wish to make many queries over small regions, and avoid the overhead of repeatedly downloading the headers. + +These use-cases are enabled by the `headers` and `data` parameters. Each of these is a boolean (0,1) flag indicating whether the server should include these sections in the response stream. By default these are both true, ensuring that well-formed streams are returned unless the client specifically requests otherwise. + # Response ## Response JSON fields