Document API calls

[RKrahl]

Add documentation of the API calls with their paths, parameters, and returns.

This is not yet finalized. As a starting point, I tried to describe the calls that are currently implemented in the API as displayed in the API explorer. But there are still many things to discuss. I open this PR also to create a place for this discussion.

The API calls are closely related to the query syntax. @garethcmurphy, since you implemented the queries in the API, would you mind providing a corresponding (starting point of a) documentation of the query syntax? I suggest that we need to discuss both in parallel.

[RKrahl]

Things that I suggest needing to be discussed include:

• For the moment, we have calls to query Dataset, Document, Instrument, and Sample. Is this enough? Do we also need calls to query the other objects in the data model?

  I suggest that this depends on the query syntax: if the queries are powerful enough to select items based on properties of related objects, such as "select all datasets that belong to document x and have a parameter named a, having a value greater then z" then this set of calls might be sufficient.

• Some calls have an id path parameter, such as GET /datasets/{id}. For this to make sense, we would need an id property in the corresponding objects in the data model. This is currently not always the case AFAICS.

• We need to define the return values. In particular, for the calls returning objects from the data model, we need to decide which related objects are to be included if any. Should a dataset include its parameters and/or files?

• Do we really need the counting calls GET /documents/count, GET /instruments/count, and GET /samples/count? A somewhat more versatile approach might be to have an optional "aggregate" parameter in the search calls or an "aggregate" clause in the query syntax. Then, one could call GET /documents with aggregate=count in place of GET /documents/count.

• The GET /datasets/{id}/metadata call would need a parameter indication the name of the metadata format. We would also need a call to query the availble metadata formats for a dataset. The return would depend on the selected metadata format.

• Finally, a purely aesthetical issue: the calls are currently in the plural (GET /datasets). At least for the call to get a single dataset, it would make more sense to write the call in the singular (GET /dataset/{id}).

[RKrahl]

More issues to discuss:

• I added a note that we won't have authentication in the first version, as discussed in Trieste.
• What about file download? I guess WP4 might need access to the real data.
• What about the creation of new datasets as a result of data analysis? (I guess that will be the only case of write access that we will consider.)

[garethcmurphy]

• Query for persons may (or may not) have GDPR implications - this could be left out
• A call to a dataset will need to include File information for WP4 use case
• The count calls are generated for free by LoopBack, but we could rename them, although I don't see the added value.
• We can have GET /datasets/metadataFormats or GET /datasets/{id}/metadataFormats. Possibly each Format should always exist for a given dataset? This might help with validation
• The plural format datasets is a LoopBack convention - I suggest we stick to it for ease of use - all other things being equal

[garethcmurphy]

• file download, we assume WP4 will want to use Jupyter in-place, so they need location of file but not physical file
• Write access/file creation, currently not supported/planned by WP4, AFAIK.