Need to define what is included in the results of the API calls

[RKrahl]

The current API call documentation is not yet specific enough about the return values. In particular, it is not defined which related objects are to be included with a returned object. For instance, the GET /datasets/{id} call returning a dataset might need to include its parameters and files, otherwise there would be no way to retrieve those parameters or files at all.

I can see two possible options to achieve this: either

• define for each call in the API a fixed set of related objects to include with the returned object, or

• add a includes query parameter to allow the client to define what it needs to be included. E.g. a GET /datasets/{id}?includes=parameters&includes=files call would include the parameters and the files, but not the techniques with the dataset.

The latter option would be more versatile and easier to adapt to future extensions but also require a little more effort in the implementation. The first option would require very careful planning to avoid omitting things that turn out to be essential later on.

Furthermore, there are different options how the inclusion of related objects can be done: either

• directly include the full JSON objects as in this example dataset:

  {
    "id": 1385,
    "title": "e243856",
    "creationDate": "2017-05-04T03:04:57",
    "isPublic": false,
    "techniques": [
        {
            "name": "XMCD"
        },
        {
            "name": "NEXAFS"
        }
    ]
  }

• or include only the ids, as in:

  {
    "id": 1385,
    "title": "e243856",
    "creationDate": "2017-05-04T03:04:57",
    "isPublic": false,
    "samples": [27, 45, 88]
  }

  The second sample related to this dataset could then retrieved in a subsequent GET /samples/45 call. This option would only work for Dataset, Document, Instrument, and Sample, because for other object types, we do not have a call to retrieve them later on.

[garethcmurphy]

We will include the full object and not the id for the reasons stated above

[zjttoefs]

@henrikjohansson712 we talked about this. I think there may be a statement in the docs on github here now. Could you point this out and make sure that is transferred to the deliverable test, so we can close this?

[henrikjohansson712]

The API calls document has been updated to state that no relations are included by default.