Use case: image API – hypermedia links

Objective: finding the meaning of hypermedia links

A general-purpose reasoner can combine a resource (an image) and its hypermedia links (thumbnail) to uncover the meaning of these links.

Again, your generic agent does not need domain knowledge (thumbnails, pixels), because RESTdesc explains the effect of following a certain hypermedia link.

Your agent knows an online image

Previously, we have looked at the case where your agent has a local image.
This time, we consider the case where your agent has access to an online image.
This image might have different representations, and accompanying metadata.
For example, /images/37 might have these metadata (server_image.n3):

@prefix ex: <http://example.org/image#>.

</images/37>
   ex:comments </images/37/comments>;
   ex:smallThumbnail </images/37/thumb>;
   ex:mediumThumbnail </images/37/thumb_med>;
   ex:belongsTo </albums/6>.

Basically, this image has several typed hypermedia links to related resources:

a comments resource (ex:comments)
thumbnail resources (ex:smallThumbnail and ex:mediumThumbnail)
an album resource (ex:belongsTo)

The concept of supplying hypermedia links with representations is often called HATEOAS or Hypermedia As The Engine Of Application State.
The idea is that every representation should point to next steps a client can take.

Your agent wants to indicate the meaning of links

The challenge is to make your generic agent indicate the meaning of these links.
The ex: link types obviously belong to a proprietary vocabulary, specifying comments, thumbnails, etc. for one specific API.

Thanks to RESTdesc descriptions, the effect of following hypermedia links gets defined in terms of existing vocabularies.
For example, small thumbnails are explained here (description_thumbnail.n3):

@prefix ex: <http://example.org/image#>.
@prefix http: <http://www.w3.org/2011/http#>.
@prefix dbpedia: <http://dbpedia.org/resource/>.
@prefix dbpedia-owl: <http://dbpedia.org/ontology/>.

{ ?image ex:smallThumbnail ?thumbnail. }
=>
{
  _:request http:methodName "GET";
            http:requestURI ?thumbnail;
            http:resp [ http:body ?thumbnail ].

  ?image dbpedia-owl:thumbnail ?thumbnail.
  ?thumbnail a dbpedia:Image;
             dbpedia-owl:height 80.0.
}.

This description explains that
IF your resource has a smallThumbnail link
THEN you can perform a GET request to the linked resource,
which will return a thumbnail of the image with height 80 pixels.

A reasoner connects the links and the description

Similarly, your agent can use a reasoner to obtain the concrete request details.
Here is what happens when we give EYE a) the image data and b) the description:

$ eye --nope --pass server_image.n3 description_thumbnail.n3

@prefix ex: <http://example.org/image#>.
@prefix http: <http://www.w3.org/2011/http#>.
@prefix dbpedia: <http://dbpedia.org/resource/>.
@prefix dbpedia-owl: <http://dbpedia.org/ontology/>.

</images/37> ex:comments </images/37/comments>.
</images/37> ex:smallThumbnail </images/37/thumb>.
</images/37> ex:mediumThumbnail </images/37/thumb_med>.
</images/37> ex:belongsTo </albums/6>.
_:sk0 http:methodName "GET".
_:sk0 http:requestURI </images/37/thumb>.
_:sk0 http:resp _:sk1.
_:sk1 http:body </images/37/thumb>.
</images/37> <http://dbpedia.org/ontology/thumbnail> </images/37/thumb>.
</images/37/thumb> a <http://dbpedia.org/resource/Image>.
</images/37/thumb> <http://dbpedia.org/ontology/height> 80.0 .

EYE can generate the above result in your browser:

http://eye.restdesc.org/?data=http://notes.restdesc.org/2011/images/server_image.n3&data=http://notes.restdesc.org/2011/images/description_thumbnail.n3

Your agent executes the resulting instructions

The instantiation of the description tells your agent that it should perform a GET request on /images/37/thumb to receive an 80px thumbnail of /images/37.

previous – overview – next

Notes on RESTdesc