From 6a893f16e1cde0ee95cf41c41f3ed66e38a72775 Mon Sep 17 00:00:00 2001 From: John Marshall Date: Tue, 10 Aug 2021 17:28:49 +0100 Subject: [PATCH] Add optional HTTP 426 response for requests for index files Clients attempting to access a resource directly, rather than via the htsget protocol, will likely also request index files alongside the requested resource. Add a section discussing how servers MAY respond with an HTTP 426 Upgrade Required status code, which provides a way to tell the client to switch to the htsget protocol. --- htsget.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/htsget.md b/htsget.md index 4e27cfc99..c51fcc6c3 100644 --- a/htsget.md +++ b/htsget.md @@ -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 @@ -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/`, such a client could make requests for `/reads/.bai` and/or `/reads/.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 `` 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.