Notes on RESTdesc

Semantic descriptions for hypermedia APIs.

Use case: image API – planning

Objective: a plan for your goal

A general-purpose reasoner can, starting from your assets (a local image), create a plan to reach your goal (a thumbnail of that image) using RESTdesc descriptions.

Your generic agent can, with that plan, accomplish your goal using hypermedia.

Your agent has an image

Similar to the first case, your agent has access to your image myphoto.jpg.
In RDF, this becomes (agent_image.n3):

@prefix dbpedia: <>.

<myphoto.jpg> a dbpedia:Image.

You have a goal

This time, you're not discovering possibilities, but have a predefined goal in mind:
obtaining a thumbnail of your image.
In RDF, this becomes (agent_goal.n3):

@prefix dbpedia-owl: <>.

<myphoto.jpg> dbpedia-owl:thumbnail _:thumbnail.

The reasoner finds a plan

Since your generic agent has no knowledge on images and thumbnails, it does not know which hypermedia links to follow. Therefore, the reasoner creates a plan.

We supply a) the image data, b) the descriptions, and c) the goal to the reasoner.
It returns this result:

$ eye --nope --quick-answer agent_image.n3 description_images.n3 description_thumbnail.n3 --query agent_goal.n3
@prefix ex: <>.
@prefix http: <>.
@prefix dbpedia: <>.
@prefix dbpedia-owl: <>.

<myphoto.jpg> a <>.
_:sk0 http:methodName "POST".
_:sk0 http:requestURI "/images/".
_:sk0 http:body <myphoto.jpg>.
_:sk0 http:resp _:sk1.
_:sk1 http:body <myphoto.jpg>.
<myphoto.jpg> ex:comments _:sk2.
<myphoto.jpg> ex:smallThumbnail _:sk3.
<myphoto.jpg> ex:mediumThumbnail _:sk4.
<myphoto.jpg> ex:belongsTo _:sk5.
_:sk6 http:methodName "GET".
_:sk6 http:requestURI _:sk3.
_:sk6 http:resp _:sk7.
_:sk7 http:body _:sk3.
<myphoto.jpg> <> _:sk3.
_:sk3 a <>.
_:sk3 <> 80.0 .

EYE can generate the above result in your browser:

Your agent executes the resulting plan

The above plan contains two requests that need to be executed in a specific order.
This order is fully determined by the dependencies between the requests.

First, your agent executes a POST request to upload the image.
If all goes according to plan, it receives a representation of this image in return, containing various hypermedia links, including a smallThumbnail link.

Your agent follows this link, whose exact URI was unknown during planning and therefore temporarily indicated with a placeholder _:sk3.

As a result, your agent can offer you the requested thumbnail of your image.
This is the HATEOAS way, since your agent follows the actual links at runtime.