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`.