Add Download API specification

[jbygdell]

Related issue(s) and PR(s)

This PR closes #1378 .

Description

The /file/{fileId}: is optional since the same functionality exists in the /file endpoint. Although it provides a more convenient way to get a file out.

Endpoints

/file - endpoint that takes query arguments to return a file by ID or path, the dataset name is a required parameter.
/file/{file_stable_id} - endpoint that returns the file withe the corresponding stable_id

/info/datasets - returns a list of datasets the user has access to
/info/datasets/{dataset_name} - returns information about the requested dataset
/info/datasets/{dataset_name}/files - returns information about the files in the dataset

How to test

Paste the contents of the yaml file into: https://editor-next.swagger.io/ for a nicer view

[pontus]

Suggested change

	content:
	headers:
	'Content-Disposition: attachment; filename="filePath"'
	content:

?

[jbygdell]

Not really, if you request a file by stable ID that should be the filename in the header.

[pontus]

Fair, would this be useful enough that we should put the basename there or shall we skip?

[jbygdell]

Let's skip this one. It's not likely that someone will try to download a file this way using a browser anyways.

[pontus]

Suggested change

	/file/{fileId}:
	/file/{datasetId}/{fileId}:

? Or should it explicitly be possible to fetch a file when knowing the fileId?

[jbygdell]

File stable ID is a unique entity and since the authorization step checks whether or not the user has permission to access the file or not this should be ok.

[pontus]

I agree that it should be okay from a security standpoint and normally I'm all for not being lazy if it helps down the line, but here I'm a bit uncertain if there is a benefit in supporting this worth the added complexity.

[jbygdell]

Adding the datasetID would make the authorization step easier/faster but then again is it really needed?
One problem that might arrive here is if the dataset ID is an URL.

[pontus]

I think we agree that it's not strictly needed, but the flow gets easier (should not be overly complex but compared to other things in download it's a lot). We should maybe mull on it for a while.

(Values for datasetID can be managed through encoding.)

[MalinAhlberg]

Looks nice! Added some comments.

[MalinAhlberg]

Not /health?

sensitive-data-archive/sda-download/api/api.go

Line 74 in 5218110

router.GET("/health", healthResponse)

[jbygdell]

health or ready serve the same purpose

[MalinAhlberg]

I know, I was just wondering if it would make sense to keep the same endpoint name 🙃

[nanjiangshu]

If there's no special reason, I agree with @MalinAhlberg that it is better to keep the same endpoint name.

[pahatz]

Looks good!

[MalinAhlberg]

In general, I think this looks very good!
I'm a bit confused about the start/end parameters vs the Range header, though. Are they to be used in exactly the same way? Ie is this

"End of requested data in the form of the 0-index of the first octet not included in the response. That is, data delivered will have octet indices in the closed-open set [start,end). Defaults to end of file if not set"

true for the end of the range to? And exactly how should the range be formatted? "Range: bytes=20-200"?

[jbygdell]

In general, I think this looks very good! I'm a bit confused about the start/end parameters vs the Range header, though. Are they to be used in exactly the same way? Ie is this

"End of requested data in the form of the 0-index of the first octet not included in the response. That is, data delivered will have octet indices in the closed-open set [start,end). Defaults to end of file if not set"

true for the end of the range to? And exactly how should the range be formatted? "Range: bytes=20-200"?

Range headers has to adhere to the specification like what you wrote above. But also this is correct "Range: bytes=20-200, 30-400"

The query parameters on the other hand you can supply one or both, hence the logic about inferring the missing one.

[MalinAhlberg]

Nice!