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

Define optional HTTP 426 response for requests for index files #665

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Define optional HTTP 426 response for requests for index files #665

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
17 changes: 17 additions & 0 deletions htsget.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,7 @@ InvalidAuthentication | 401 | Authorization provided is invalid
PermissionDenied | 403 | Authorization is required to access the resource
NotFound | 404 | The resource requested was not found
PayloadTooLarge | 413 | POST request size is too large
HtsgetRequired | 426 | An htsget request is required to access the resource
UnsupportedFormat | 400 | The requested file format is not supported by the server
InvalidInput | 400 | The request parameters do not adhere to the specification
InvalidRange | 400 | The requested range cannot be satisfied
Expand Down Expand Up @@ -626,6 +627,22 @@ The client obtains the data block by decoding the embedded base64 payload.

Note: the base64 text should not be additionally percent encoded.

## "Upgrade Required" response for index file requests

A client attempting to access a resource directly, rather than via the htsget protocol, will likely also request index files alongside the requested resource.
For example, in preparing to access `/reads/<id>`, such a client could make requests for `/reads/<id>.bai` and/or `/reads/<id>.csi`.

When a request does not refer to an extant served resource (thus would otherwise result in a 404 `NotFound` error or similar), contains a known BAI/CSI/CRAI/TBI/etc index extension, and particularly when trimming that extension **does** result in an `<id>` that denotes an extant resource, that is a request for an apparent index file.
A server MAY respond to such requests by replying with an `HtsgetRequired` error:

HTTP/1.1 426 Upgrade Required
Upgrade: htsget/1.3.0
Connection: Upgrade

{ "htsget": { "error": "HtsgetRequired", "message": "..." } }

Upon receiving an `HtsgetRequired` error, clients SHOULD switch to making requests for genomic regions via the htsget protocol, rather than attempting to use the index (which is not available) to make client-side HTTP Range requests on the resource.

## Reliability & performance considerations

To provide robustness to sporadic transfer failures, servers should divide large payloads into multiple data blocks in the `urls` array. Then if the transfer of any one block fails, the client can retry that block and carry on, instead of starting all over. Clients may also fetch blocks in parallel, which can improve throughput.
Expand Down