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 https://github.com/lobid/lodmill/issues/297#issuecomment-43178953 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 https://github.com/lobid/lodmill/issues/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: https://github.com/lobid/lodmill/issues/353, https://github.com/lobid/lodmill/issues/357, https://github.com/lobid/lodmill/issues/449,

[acka47]

We should consider switching to https with API 2.0.

[jschnasse]

For Api 2.0 , I´d suggest another trick. It would be nice to always get a prefLabel as a side car to all occurrences of @id (in document AND in context) . The usage of prefLabel would give clients a simple, unified and intuitive way to access the index and to mock views on lobid data. It can also be useful for configuring the index (e.g. boosting prefLabel). Some examples:

• in case of gnd-ids the preferredName should be provided as prefLabel, same for gnd-subjects
• for skos vocabs, a prefLabel comes together with the uris
• for the @ids in the context you can use tools like etikett

[acka47]

It would be great to support Triple Fragment Patterns with API 2.0. This would enable people to run SPARQL queries against lobid. There already exists a Triple Pattern Fragments server for Java.

[acka47]

As API 2.0 has been officially launched, I am closing this issue.