Re: JSON Hyper-Schema

Hi,

Am 05.04.2015 um 13:33 schrieb Miguel:
> Hi everybody,
> thanks again for the feedback.
> I have been traveling these days and delayed the reply, but I would
> like to keep discussing these ideas with you.
> 
> I have found Jsonary [1,2], that is a tool that allows to use JSON
> Hyper Schema the way I was thinking too: to add "semantics" to
> existing JSON-based web APIs.

Basically, that seems to involve two things on the server side:

1. you want to describe the attributes of the existing API. For that you
need a suitable vocabulary (preferably one that is already available,
see schema.org and lov [6]) and a json-ld context which maps every
attribute to a linked data property. Json-LD defines a link header which
allows to apply the context without rewriting the current response [5].
Markus has built a sample api [10] which has one jsonld context file per
resource. In Markus' sample service the context is linked in via an
@context attribute, but you can also achieve that with a link header.
Note that the context describes the attributes in the json, not the
possible interactions.

2. you want to describe the interactions. With hydra, you can write an
ApiDocumentation and use yet another link header to link it into the
existing service responses using the extension rel defined by the hydra
spec [7]. See below [1] for an example of an ApiDocumentation.

Now the challenge is to apply the link headers to a service you do not
own. You might use a small proxy service to do that. It does nothing but
adding the two link headers.

The client must be able to interpret the headers. You might want to take
a look at npm-jsonld [3] for Javascript or jsonld-java [4] for Java.
These libraries can apply the json-ld context, so that the client sees
json-ld. You could also use these libs to produce proper json-ld with
mime-type application/json-ld in your proxy.

We do not have standalone client libraries yet which can make sense of
the linked ApiDocumentation. However, chances are that the Hydra-Browser
[2] will understand your enhanced service already :)

At some point we will hopefully have such a client library in hydra-java
[9], so that Java clients can make use of the hydra descriptions.
Disclaimer: I am the initiator of hydra-java :)

> The author, Geraint Luff, has even built as proof of concept an
> adapter for part of Facebook API [3].
> What I like of that approach is that is mostly based on a declarative,
> static specification of the mapping (using JSON Hyper Schema), with
> just a few tweaks for authentication.
> 
> I would like to find something similar but based on the RDF data
> model, in order to adapt native APIs like Facebook or Gmail to a
> Linked Data standard API like Hydra Core or LDP Server.
> I am trying to build a draft example of a Gmail adapter using Hydra
> Core and JSON-LD contexts, but I still have to better understand Hydra
> Core.
> 
> The Restbucks example was very useful to understand a lot of Hydra concepts.
> But in that example the affordances are always dynamically attached to
> instance data.
> I guess that the Hydra concepts of Class, Property, Link and Operation
> allow also a static description of an API, but I am still not
> completely sure of how to do it.
> It would be useful to have an example of such use of Hydra.

An example for a static ApiDocumentation is in Markus' event API demo
[1], and the described service is running at [2].

See https://github.com/HydraCG/Specifications/issues/75 and the related
mailing list exchange for an idea how to make the ApiDocumentation more
dynamic, depending on privileges of the current user.

The idea was that there may be a static ApiDocumentation and a dynamic
ApiDocumentation. The static ApiDocumentation helps an implementor
because it describes all possible transitions, but at runtime the client
must use the dynamic ApiDocumentation.

Personally I fully understand the usefulness of a complete
ApiDocumentation for the implementor, which also describes when and why
certain transitions might not be available. But if I have dynamic
transitions at runtime, I would opt for transitions right in the
response. If the externalized ApiDocumentation must be revalidated at
all times, the client must make two requests.

If however an API has no dynamic transitions, then it makes more sense
to have only a static ApiDocumentation - it makes your responses much
smaller.

HTH,
Dietrich


> 
> [1] http://jsonary.com/
> [2] https://github.com/jsonary-js/jsonary
> [3] http://jsonary.com/walkthrough-facebook/stage2-schemas/
> 

[1] http://www.markus-lanthaler.com/hydra/event-api/vocab
[2] http://bit.ly/hydra-console-event-api
[3] https://www.npmjs.com/package/jsonld
[4] https://github.com/jsonld-java/jsonld-java
[5] http://www.w3.org/TR/json-ld/#interpreting-json-as-json-ld
[6] http://lov.okfn.org/dataset/lov/
[7]
http://www.w3.org/ns/hydra/spec/latest/core/#discovering-a-hydra-powered-web-api
[8]
https://github.com/spring-projects/spring-hateoas/blob/master/src/main/java/org/springframework/hateoas/client/Rels.java
[9] https://github.com/dschulten/hydra-java
[10] http://www.markus-lanthaler.com/hydra/event-api/
[11]
http://docs.spring.io/spring-hateoas/docs/current/reference/html/#client.traverson

Received on Sunday, 5 April 2015 15:42:30 UTC