SEEK API: item relations in list requests

[Ole Trenner]

Hi guys,

I am currently working on a service which integrates with Seek. At some point I want to show a tree of accessible Projects, Studies, Assays, and Investigations. When using the API endpoints for these entities I get only a limited set of fields, e.g. for 'investigations':

{

      "id": "1",

      "type": "investigations",

      "attributes": {

        "title": "..."

      },

      "links": {

        "self": "/investigations/1"

      }

},

...

Is it possible to adjust the returned fields (especially: to include the relationships) of the items, maybe with a request parameter or a custom request?

I know I could use the 'read' endpoint but then I would have to perform many requests to get these details for the individual entities.

I also know that I could use "hierarchical" requests like "/projects/1/investigations" but that would also require multiple requests (although not as many).

I would really appreciate any pointers on how to approach this :)

Thanks for your help and all the good work you're doing! Best,

Ole Trenner

[Alan R Williams]

Hello Ole

Response inline

On 06/09/2019 08:57, Ole Trenner wrote:
> Hi guys,
>
>
> I am currently working on a service which integrates with Seek. At some
> point I want to show a tree of accessible Projects, Studies, Assays, and
> Investigations. When using the API endpoints for these entities I get
> only a limited set of fields, e.g. for 'investigations':
>
> {
>       "id": "1",
>       "type": "investigations",
>       "attributes": {
>         "title": "..."
>       },
>       "links": {
>         "self": "/investigations/1"
>       }
> },
> ...
>
>
> Is it possible to adjust the returned fields (especially: to include the
> relationships) of the items, maybe with a request parameter or a custom
> request?

At the moment no. To follow the JSON API spec, the investigations are a
list of "resource identifier objects".

<quote>
A “resource identifier object” is an object that identifies an
individual resource.

A “resource identifier object” MUST contain type and id members.

A “resource identifier object” MAY also include a meta member, whose
value is a meta object that contains non-standard meta-information.
</quote>

From my reading of the JSON API, the correct way to do this is to have
a compound document.

As in this example:

{
"data": [{
"type": "articles",
"id": "1",
"attributes": {
"title": "JSON:API paints my bikeshed!"
},
"links": {
"self": "http://example.com/articles/1"
},
"relationships": {
"author": {
"links": {
"self": "http://example.com/articles/1/relationships/author",
"related": "http://example.com/articles/1/author"
},
"data": { "type": "people", "id": "9" }
},
"comments": {
"links": {
"self": "http://example.com/articles/1/relationships/comments",
"related": "http://example.com/articles/1/comments"
},
"data": [
{ "type": "comments", "id": "5" },
{ "type": "comments", "id": "12" }
]
}
}
}],
"included": [{
"type": "people",
"id": "9",
"attributes": {
"first-name": "Dan",
"last-name": "Gebhardt",
"twitter": "dgeb"
},
"links": {
"self": "http://example.com/people/9"
}
}, {
"type": "comments",
"id": "5",
"attributes": {
"body": "First!"
},
"relationships": {
"author": {
"data": { "type": "people", "id": "2" }
}
},
"links": {
"self": "http://example.com/comments/5"
}
}, {
"type": "comments",
"id": "12",
"attributes": {
"body": "I like XML better"
},
"relationships": {
"author": {
"data": { "type": "people", "id": "9" }
}
},
"links": {
"self": "http://example.com/comments/12"
}
}]
}

The article is as usual, but the resources it references are given in
the included element. So the JSON document includes the author and two
comments.

Is this similar to what you want?

It is not clear (to me) from the JSON API specification if you can
selectively choose which kind of resource to include e.g. just the
author, or if you have to include all/none of them.

I think this could be done by adding an option to the call e.g.

https://fairdomhub.org/projects/51?include=all

or

https://fairdomhub.org/projects/51?include=investigations,data_files

I will need to look at the JSON serialization code to see how easy this
is. (Assuming it fits your need.)

Alan

> I know I could use the 'read' endpoint but then I would have to perform
> many requests to get these details for the individual entities.
>
> I also know that I could use "hierarchical" requests like
> "/projects/1/investigations" but that would also require multiple
> requests (although not as many).
>
>
> I would really appreciate any pointers on how to approach this :)
>
>
> Thanks for your help and all the good work you're doing! Best,
> Ole Trenner
>

> --
> If you have installed SEEK - please take a moment to fill out our
> registration form at http://www.seek4science.org/seek-registration
> ---
> You received this message because you are subscribed to the Google
> Groups "SEEK" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to seek4science...@googlegroups.com
> <mailto:seek4science...@googlegroups.com>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/seek4science/4fe166a9-bbb6-462f-9b4d-e497dfc8dd82%40googlegroups.com
> <https://groups.google.com/d/msgid/seek4science/4fe166a9-bbb6-462f-9b4d-e497dfc8dd82%40googlegroups.com?utm_medium=email&utm_source=footer>.

[Ole Trenner]

Hello Alan,

First of all, thanks for the help! The described compound response sound like a nice solution to my problem. I wouldn't actually mind if the response contained *all* relations (because bandwidth is much less of a problem than request latency), but having the possibility to specify the required relation types is definitely an attractive option!

Just for clarification: Did you mean that this is an available solution *right now*? Or did you mean that this would have to be implemented and added to a future release of the API? If so, would you actually consider doing it? And in what kind of time frame? Is there anything I can do to support the process?

Thanks again for taking the time and getting back to me!

Best,

Ole Trenner

[Alan R Williams]

On 09/09/2019 15:56, Ole Trenner wrote:
> Hello Alan,
>
> First of all, thanks for the help! The described compound response sound
> like a nice solution to my problem. I wouldn't actually mind if the
> response contained *all* relations (because bandwidth is much less of a
> problem than request latency), but having the possibility to specify the
> required relation types is definitely an attractive option!
>
> Just for clarification: Did you mean that this is an available solution
> *right now*?

No

> Or did you mean that this would have to be implemented and
> added to a future release of the API?

Yes

> If so, would you actually consider
> doing it?

It seems a sensible extension, assuming the JSON serializer can do it.

> And in what kind of time frame?

I am not sure. A lot depends on what other work is needed.

> Is there anything I can do to
> support the process?

Almost certainly. Do you know Ruby/Rails? Even if not, you can still
help testing.

> Thanks again for taking the time and getting back to me!
>
> Best,
> Ole Trenner

Alan

> --
> If you have installed SEEK - please take a moment to fill out our
> registration form at http://www.seek4science.org/seek-registration
> ---
> You received this message because you are subscribed to the Google
> Groups "SEEK" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to seek4science...@googlegroups.com
> <mailto:seek4science...@googlegroups.com>.
> To view this discussion on the web visit

> https://groups.google.com/d/msgid/seek4science/d781d169-6ada-44a7-bba5-9fc7daafcf08%40googlegroups.com
> <https://groups.google.com/d/msgid/seek4science/d781d169-6ada-44a7-bba5-9fc7daafcf08%40googlegroups.com?utm_medium=email&utm_source=footer>.

[Alan R Williams]

OK I have tried it out, and it will be possible to tell the serializer
to include referenced resources, and even resources of those resources.

The main issues I can see is that

a) there will be relationships in the database that should never be
serialized, and also

b) we need to ensure that this serialization does not allow a back route
to resources you do not have the permission to see.

Alan

[Ole Trenner]

Hello Alan,

That sounds really promising, thank you! I would be happy to help the process. I know a little Ruby/Rails, but not enough to start this on my own in an unfamiliar project. But maybe I can do some testing and/or documentation work! I would appreciate it if you could point me into the right direction...

Thanks and best,

Ole Trenner