Specify the conditions we would expect from the VFDB-API

[AndyDaniel1]

The VFDB has asked us to specify the conditions that we would expect from the API. Let us discuss this topic in the next few weeks.

[rreitmann]

• REST API with OpenAPI Documentation (fka Swagger)
• Health Endpoint for checking whether the service is alive
• Test system for testing integrations

[polx]

So. Do I understand properly that:

• the encoding that goes through the rest api does not matter (xml, json, rdf, yml, ...)
• the nature of the exchanged information remains to be defined

?

thanks

[rreitmann]

@polx

• We would prefer JSON (utf-8 encoded) as representation of the resources
• use a standardized authentication scheme (e.g. http basic over ssl)
• the schema of the resources depends on the data you want to collect, we can review it as soon as you have an OpenAPI like documentation

[polx]

We have a clear case of the function of an OAI-PMH provider Endpoint. This is a form of REST interface but whose protocol was created even before the word REST was coined. My problem is that I found no OpenAPI effort yet that describes OAI-PMH.

(part of the fun is that the OpenAPI-Initiative calls itself OAI which is quite irrespectful).

[rreitmann]

I have not been aware of OAI yet. Have to look into it....

[polx]

How is the look going?

[rreitmann]

Sorry, here are my remarks:

• OAI-PMH uses HTTP as transport protocol but does not leverage the semantics of HTTP (URLs=nouns, HTTP-methods=verbs) thus I would not call it RESTful and there will be no simple OpenAPI-Doc generation
• My first impression is that our role in the OAI-PMH model would be "repository" thus we would need to implement an interface for the harvester, which we have currently not planned
• From the documentation I cannot identify the endpoint/verb to which we would send our metadata

[rreitmann]

@polx Did I get the OAI-PMH model right that we would be a data provider and we would need to implement an endpoint for your harvester? If not, can u please point me to the part of the documentation of the OAI-PMH model which would be relevant for us?

[polx]

Hello @rreitmann : Well, I disagree with the non-RESTful interpretation. POSTing or GETting a request is just as much a resource request. The fact that the term verb is used at the OAI-PMH level does not mean that it needs to be the same concept as the verb of the REST world (which is tightly bound to a CRUD interpretation which has no place as far as I can tell).

In our case, considering sizes, I think that using GET is rather good practice as it makes things a tick more cache-friendly and we are far from overloading the length of URLs.

As to who is a repository and who is a provider. I think that it is not unlikely that we both are both at least after some time. Or?

[rreitmann]

@polx I think it is not important to argue about RESTfullness at this moment. But OAI-PMH is quite similar to SOAP and https://stackoverflow.com/questions/1950764/why-isnt-soap-based-web-service-restful

The important thing is to clarify the roles and therefore who implements what. In OAI-PMH terms we would be one Data Provider and you would be a Service Provider offering "value-added services" with the metadata harvested from the Repositories of all Data Providers. The Repositories implement the protocol as defined here so that the harvester can retrieve the records from the Repository and store it for the Service Provider.

Implementing that protocol on our side is far more complicated then simply PUTting our metadata (aka as data module, data package,...) in one HTTP endpoint offered by you (like da|ra) does. That way we can create and update the metadata on your side on every release of a data package. Furthermore it is much more efficient sending you only the data which has changed instead of getting harvested regularly although nothing has changed.

[rreitmann]

Here are some tools which would help implementing the Repository Endpoints: http://www.openarchives.org/pmh/tools/

And here are some guidelines: http://www.openarchives.org/OAI/2.0/guidelines.htm

Here are some java libraries: https://github.com/DSpace/xoai https://github.com/OCLC-Research/oaiharvester2 https://mvnrepository.com/artifact/org.dspace.modules/oai/6.3