RE: Best API to consume SKOS data

Hi Vladimir,

Now that you mention OpenAPI, one further question could be to which extent it is possible to combine them with those you mentioned before.
The first APIs you mentioned (at least LDP/GraphQL) are much oriented at content management (e.g. LDP is API for linked data, GraphQL provides a graph perspective over your - not necessarily graph - data) while OpenAPI stands on a different dimension.
It provides specs for a descriptor (the YAML file) and supporting technologies (e.g. for going back and forth between API generation and API documentation) which can then implement plain Web API (possibly fully following REST paradigm…or not) or somehow adhere to other APIs in any other domain/content model.
For instance, I wonder (I guess?) that requests and responses of LDP could be modeled using Swagger. The requests can be described with Swagger’s metadata and the response in Swagger is open wrt to the adopted media-type, thus including any serialization of RDF. The introspection is not in RDF.
Another good point for Swagger is its use of (an extended subset of) JSON Schema Specification.

My reluctancy towards the three API of your previous email (yet, it was not a rejection) is that I didn’t see much in the use of content-oriented API (e.g. we have SPARQL, do we need GraphQL?) while I got much more from the general environment provided by Swagger.
Coming back to available implementations, my two cents on those I know of:

  *   AFAIK, SKOSMOS developers use OpenAPI/Swagger [1]
  *   About ST, we are not – currently – using OpenAPI/Swagger, due to a previous framework we had previously developed for API generation in our specific domain (editing and consuming RDF). We don’t write the controller code and instead rely on a vocabulary of Java Annotations strongly tied to our domain (RDF) to describe the services. So, starting from a very compact java method declaration (an example in [2]), we have the automatic generation of the controller code. Besides the contribution of the rich semantics provided by the annotations, the code is much compact also because we have a lot of business information (queried project, write graph, read graphs etc…) all held in a context object [3] that is always handed to server without being in the method’s signature.
However, we have had a very positive experience with OpenAPI/Swagger in other contexts (e.g. we adopted it in our AlignmentOrchestration API, which is consumed by ST) and, while we intend to keep our framework for controller generation which is not compatible with Swagger, we might work in the near future on integrating ST with Swagger at least for the, a-posteriori, generation of documentation and API testing UI.

Kind Regards,

Armando

[1] https://github.com/NatLibFi/Skosmos/blob/master/swagger.json

[2] https://bitbucket.org/art-uniroma2/semantic-turkey/src/6dac251994460427597891f55ca2960e1d38cde6/st-core-services/src/main/java/it/uniroma2/art/semanticturkey/services/core/SKOS.java#lines-567

[3] https://bitbucket.org/art-uniroma2/semantic-turkey/src/master/st-core-framework/src/main/java/it/uniroma2/art/semanticturkey/services/STServiceContext.java

[4] https://bitbucket.org/art-uniroma2/maple/src/master/maple-alignment-services-api/src/main/openapi/alignment-services.yaml


From: Vladimir Alexiev <vladimir.alexiev@ontotext.com>
Sent: Thursday, March 19, 2020 9:19 AM
To: public-esw-thes@w3.org
Subject: Re: Best API to consume SKOS data

CHIN selected and deployed a TMS (PoolParty) about a year ago and the Nomenclature editors are using it actively.
So it's not a question of selecting a new TMS but a quest for what would be the best API to provide for accessing the data.

CHIN have collected some API requirements (calls that would be most useful) that have specifics:

Especially regarding language and language fallbacks. Eg their website uses two flags "en vs fr" and "Canadian vs international".
I've recommended passing these as one "RDF-like" param rather than two numeric flags.
Eg "lang=en-CA" would mean "Give me prefLabels in English-Canadian if available, else in English" and correspond to this HTTP header:
Accept-Language: en-CA, en # although this allows also other English "dialects", if such were in the data.
Does any of the existing APIs implement lang filtering and fallback logic?

It may well happen that because of such specifics, a custom API will be implemented.
(A promising approach is grlc, which implements APIs as a collection of SPARQL queries).

The feedback that we seek is what FORM of API the community thinks is most appropriate.
BTW, in addition to the 3 modern standards I mentioned (LDP, Hydra and GraphQL),
we are definitely considering OpenAPI (Swagger) that provides introspection and generation of API UIs.
Even though the introspection is not RDF-based, OpenAPI is extremely popular.
grlc implements OpenAPI.


On Fri, Mar 13, 2020 at 6:27 PM Fabio Ricci <fabio.fr.ricci@gmail.com<mailto:fabio.fr.ricci@gmail.com>> wrote:
Is https://skosshuttle.ch/api/ maybe what you are searching for?