RE: On building web service clients for specific tasks

Hi Miguel,

On 9 Aug 2015 at 17:58, Miguel Casal wrote:
> Hello Hydra community!

Welcome onboard.


> Great work. I'm very intrigued with all the efforts to drive APIs
> through semantics and hypermedia. I'm trying to grasp these concepts
> coding a simple client to consume a JSON-LD + Hydra web service. This

Let us know if you have any questions or if you run into any issues.


> client would do a simple task, but instead of hard coding the URL to a
> specific end point I'm exploring ways of embedding a notion of
> resources and transitions between them.
> 
> Suppose I want to do a really simple task with a theoretical CLI that
> consumes the issue tracker API: ask a name and search for it in the
> User collection. Also assume that the API offers this possibility.
> 
> The most straightforward series of steps could be:
> 
> 1) Request JSON-LD from the entry point
> 2) Parse the result and expand it
> 3) Get the value (an URL) of the key
> "http://www.markus-lanthaler.com/hydra/api-demo/vocab#EntryPoint/users"
> 4) Perform a GET request on that URL with the name provided by the CLI
> user
> 
> At first sight it doesn't seems very HATEOAS this approach. Instead of
> hard coding URLs I assume a previous knowledge of the result's
> structure (the media type I guess).

Yes, in this case you'd couple against the shared vocabulary. The issue
tracker example is actually a bad example for this as it uses an
auto-generated vocabulary.


> Maybe in step 4 my client application should parse the vocabulary of
> EntryPoint/users, look for an specific operation (let's say
> user_search) and if it exists, try to fulfill it mapping the received
> name to some operation's parameter.

Yes.


> What are your thoughts about this?

In general, I'd try to use the Hydra ApiDocumentation as much as possible.
It can give you lots of hints depending on how well the service is
described. So, in the example you outlined above, you'd try to find a User
object whose name property has a specific name. There would be multiple ways
to achieve that (not all are supported by the demo issue tracker):

-- Crawl the complete API till you find a resource that matches the criteria
--

This is likely the simplest to implement but the slowest and most
inefficient approach.

-- Evaluate ranges (as well as rangeIncludes and similar information) and
operations --

This makes the crawl much more efficient in a lot of cases because you would
be able to narrow down the search space. Unfortunately, however, collections
often get in your way here. It is possible to describe what type of entities
a collection contains using OWL but that is difficult. We should probably
address this somehow in Hydra.

-- Use the TPF interface [1] if the server supports it --

This would give you a very generic query interface.


This are just a couple of quick ideas from the top of my hat. I'm sure there
exist many more approaches. In general, I think a combination of the latter
two is the most promising. If you can draw a "map" of the service from the
ApiDocumentation you would be able to use a whole lot of graph algorithms to
find paths from your current position to your goal. If the server gives you
more affordances, you can shortcut that by pushing some of the work to the
server.


Hope this helps. Please keep us posted with your progress.


Thanks,
Markus


[1] http://www.hydra-cg.com/spec/latest/triple-pattern-fragments/


--
Markus Lanthaler
@markuslanthaler

Received on Monday, 10 August 2015 19:52:14 UTC