Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Header and data boolean flags for htsget. #311

Closed
wants to merge 1 commit into from
Closed

Header and data boolean flags for htsget. #311

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions htsget.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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`.
</td></tr>
<tr markdown="block"><td>
`headers_only`
_optional_ integer (boolean)
</td><td>
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
</td></tr>
<tr markdown="block"><td>
`fields`
_optional_
</td><td>
Expand Down Expand Up @@ -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
Expand Down