Having worked much more closely with the REST API recently, I thought I would share some thoughts:
- Use URL parameters instead of headers for command specific parameters (e.g. filters, ranges, sorts, etc).
-
It is much easier/obvious for developers to add parameters to a URL than to change headers.
-
As a REST response should be stateless and return a repeatable value for a request, URL parameters are consistent with this. In short, a data set as defined in the complete URL (with parameters) is unique to the URL.
-
Caching based on URL can be achieved, as the URL response to the request is predictable/repeatable without further input required.
-
Having a mixture of parameters and header variables is inconsistent. This adds complexity to the client, as there are more use cases to cater for.
- Splitting requests for files and directories adds complexity to the client.
-
Without knowledge of whether the URL is a file or a directory, you have to test for both. This adds complexity to the client and increases the number of requests required to derive the path type (i.e. file or directory).
-
There are common properties of files and directories (e.g. name, date created, date modified, permissions, size, etc). Having a common data structure simplifies the client, as files/directories just become specialisations of a path.
-
GETs to a specific path could return a response derived by the underlying type, e.g. a file GET could return the content, a directory GET could return the listing.
-
Along with the above, adding a parameter filter could allow a consistent response when needed (format=json to return properties/content as a json document, format=raw to just return the content as the response body, etc). This would cater for times when you just want the content in the response body (e.g. a web browser request) vs a JSON document (e.g. when you are writing a custom client of some sort).
- There should be a common way to query paths, rather than separate NFS and DNS commands.
-
Retrieving public data via DNS and private data via NFS seems odd. Both are retrieving data and the former is not a DNS operation.
-
Having two commands to retrieve data adds complexity to the client, which needs to derive the class of data before the correct command can be identified. We shouldnāt have to derive this information from the URL - the end point should be able to derive it instead.
- Ranges are required for reads and writes.
-
This appears to be in the works for reads, but is currently non-functional (and uses header variables - see above).
-
File systems expect to be able to define a file position to read/write from/to. Being able to define these ranges allows the client to control how much data needs to be downloaded/uploaded depending on the context.
- Appending/updating writes
-
Probably also in the works, but not having this functionality adds overhead for file changes (download full file, upload full modified file). The overhead becomes unworkable with large files which are changed frequently.
-
I understand parallel writes are a problem, but parallel reads should already be feasible (at a lower level) and this could be used by the client to optimise data retrieval externally to the launcher. This would allow more flexibility at the client end.
- Persistent application authentication at the network level
-
Permissions should not be dependent on the launcher restricting access. This should be done at the network level, which would avoid cross-application access issues (having to encrypt app data, not being able to restrict raw data access, etc).
-
Assuming access to the network can be granted on presentation of a persistent access token, the launcher could instead help to manage these lower level tokens instead of its higher level tokens. The UX could still be similar, but it would allow safe_core to handle this aspect and allow any other linked client apps to offload this responsibility.
-
Having this control at the network layer would also allow multiple devices/platforms to share the same permissions layer. You could then interrogate/modify permissions across all devices easily, without having to rely on separate launcher versions, etc.
I may have forgotten some other items, but I will amend this if they come to mind. I hope this feedback helps and is received in the constructive manner intended.
EDIT: Fixed bullet formatting
.
