lobid API 2.0

[acka47]

In the past weeks we have discussed some additions to the lobid API that would result in incompatibilities with the existing API version 1.x.x and thus would mean a change to version 2.0.0.

This is the main issue to discuss the changes included in this version upgrade. Tickets for individual work packages will be linked to this issue.

[acka47]

Provide nested JSON-LD instead of flat @graph structure, see lodmill-449.

[acka47]

Add query as seperate JSON object with information on issued when, number of results etc., see comment lobid/lodmill#297 (comment) and following.

[fsteeg]

From our experience with the current API so far having different routes for different kinds of data (/person, /subject, etc.) is rather confusing. Instead, we could implement a single route (e.g. /data) and filter everything using the type query parameter.

This new route could simply be added without changing the existing routes, which we would deprecate.

Note: this does not affect our own URIs (/resource/ID, organisation/ID), which we would retain.

[fsteeg]

Having different query parameters for different field sets (id=, name=, q=) introduces much complexity on the implementation level. For a 2.0 API I'd prefer a single q= parameter for all queries, with an optional (default would be all fields, as with current q=), additional parameter (e.g. q=Essen&domain=name).

[fsteeg]

For details on the desired JSON-LD structure see:

http://manu.sporny.org/2014/json-ld-origins-2/#comment-4189

And especially lobid/lodmill#433 where the approach for lobid to get nested JSON-LD is described in detail.

[fsteeg]

To be able to seize what Elasticsearch provides out of the box in its query string syntax (see 1), we should index our data with compact keys. There is currently no way to generate a JSON-LD representation with compact keys and regular values (required for Elasticsearch) however (see 2).

[fsteeg]

Since we want a custom JSON-LD format in different ways (see previous two comments), I think we should manually create the JSON-LD representation and generate other representations from that, instead of manually creating a different representation and generating the (insufficient) JSON-LD representation from it (as we currently do).

[acka47]

We should take API 2.0 as an opportunity to also differentiate more betwen the linked data part where locally created data with links to other services (GND, GeoNames etc.) is provided and the API where the local data enriched with data from the linked this-party sources is offered. This might be achieved by pre-filtering the linked data served from /resource and /organisation URIs with a JSON-LD frame.

[acka47]

See also related issues: lobid/lodmill#353, lobid/lodmill#357, lobid/lodmill#449,

[acka47]

We should consider switching to https with API 2.0.