docs: clarifications

sda-download/api/api.md

@@ -19,13 +19,13 @@ The client can establish a session to bypass time-costly visa validations for fu
 
 ### Endpoints overview:
 
-**Data out API**:
+**[Data out API](#data-out-api)**:
 
 - `/metadata/datasets`
 - `/metadata/datasets/*dataset`
 - `/files/:fileid`
 
-**htsget**:
+**[File download requests, for htsget](#file-download-requests)**
 
 - `/s3/<datasetid>/<fileid>`
 - `/s3-encrypted/<datasetid>/<fileid>`
@@ -51,8 +51,8 @@ The files contained in a dataset are listed using the `datasetName` obtained fro
 GET /metadata/datasets/{datasetName}/files
 ```
 **Scheme Parameter**
-The `?scheme=` query parameter is optional. When a dataset contains a scheme, it may sometimes encounter issues with reverse proxies.
-The scheme can be separated from the dataset name and supplied in a query parameter.
+The `?scheme=` query parameter is optional. When a dataset name contains a scheme, such as `https://`, it may sometimes encounter issues with reverse proxies.
+This can be solved by separating the scheme from the dataset name and suppling it as a query parameter.
 ```
 dataset := strings.Split("https://doi.org/abc/123", "://")
 len(dataset) // 2 -> scheme can be used
@@ -100,28 +100,28 @@ File data is downloaded using the `fileId` from `/metadata/datasets/{datasetName
 GET /files/{fileId}
 ```
 ##### Response
-Response is given as byte stream `application/octet-stream`
-```
-hello
-```
+Response is given as byte stream `application/octet-stream`.
 ##### Optional Query Parameters
 Parts of a file can be requested with specific byte ranges using `startCoordinate` and `endCoordinate` query parameters, e.g.:
 ```
 ?startCoordinate=0&endCoordinate=100
 ```
 
-### S3 requests, for htsget
+### File download requests
+These endpoints are designed for usage with [htsget](https://samtools.github.io/hts-specs/htsget.html).
+
+The `/s3` and `/s3-encrypted` endpoints accept the same parameters, described below.
+Note that the download service may be configured to only allow encrypted file downloads.
 
 **Parameters**:
 
-*Partial file retrieval*: 
 - `startCoordinate`: start byte position in the file. If the request is for an encrypted file, the position will be adjusted to align with the nearest data block boundary.
 - `endCoordinate`: end byte position in the file. If the request is for an encrypted file, the position will be adjusted to align with the nearest data block boundary.
 
-Headers:
+**Headers**:
 
 - `Authorization: Bearer <token>` 
-- `Range: bytes=<start>-<end>`  exact positions. Overrides parameter coordinates.
+- `Range: bytes=<start>-<end>`  exact byte positions for partial file retrieval. Overrides parameter coordinates.
 - `Client-public-key: <key>` used for re-encrypting the header of the file before sending it.
 
 
@@ -132,14 +132,16 @@ HEAD /s3/{datasetid}/{fileid}
 ```
 ##### Response
 Returns the size of the unencrypted file, communicated in the response header `Content-Length`.
+Or, if the download service is configured to disallow unencrypted downloads, status `400` will be returned.
 
 #### Retreive unencrypted file
 ##### Request
 ```
 GET /s3/{datasetid}/{fileid}
 ```
 ##### Response
-Returns the unencrypted file.
+Returns the unencrypted file, as byte stream `application/octet-stream`.
+Or, if the download service is configured to disallow unencrypted downloads, status `400` will be returned.
 
 
 #### Retreive size of encrypted file
@@ -156,4 +158,4 @@ Returns the size of the unencrypted file, communicated in the response header `C
 GET /s3-encrypted/{datasetid}/{fileid}
 ```
 ##### Response
-Returns the unencrypted file.
+Returns the unencrypted file, as byte stream `application/octet-stream`.