Use case: image API – instructions

Objective: concrete instructions for generic agents

A general-purpose reasoner combines local assets (your image) and a RESTdesc description (uploading images) into concrete instructions (upload your image) that your agent can execute (HTTP request).

Your generic agent does not require any domain knowledge (images) since the RESTdesc description, interpreted by the reasoner, contains all semantics.

Your agent has an image

Suppose your agent has access to one of your images called myphoto.jpg.
This fact might be expressed as follows in RDF (agent_image.n3):

@prefix dbpedia: <http://dbpedia.org/resource/>.

<myphoto.jpg> a dbpedia:Image.

Note that we are talking about generic agents, so your agent doesn't necessarily need to know what a dbpedia:Image is.

Your agent discovers what it can do with this image

Your agent would now like to know what it can do with this image.
(Remember: it might even not know what “an image” is.)

First, it discovers descriptions of the APIs it has access to.
The list of APIs can be added beforehand or at runtime.
Using for example HTTP OPTIONS, it retrieves this API info (description_images.n3):

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

{
  ?image a dbpedia:Image.
}
=>
{
  _:request http:methodName "POST";
            http:requestURI "/images/";
            http:body ?image;
            http:resp [ http:body ?image ].
  ?image ex:comments _:comments;
         ex:smallThumbnail _:thumb;
         ex:mediumThumbnail _:mediumThumb;
         ex:belongsTo _:album.
}.

This RESTdesc description explains how to upload an image:
IF you have an image
THEN you can POST a request to /images with this image in the body,
which will return a representation of the image.

A reasoner connects the image and the description

Now, your agent has an image and a description.
But how can it connect these to know what to do?

The agent needs not understand N3, but can use a reasoner such as EYE or cwm.
Here, your agents starts EYE with a) the image data and b) the description.
The result returned by EYE is in plain RDF format:

$ eye --nope --pass agent_image.n3 description_images.n3

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

<myphoto.jpg> a <http://dbpedia.org/resource/Image>.
_: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.

EYE can generate the above result instantly in your browser:

http://eye.restdesc.org/?data=http://notes.restdesc.org/2011/images/agent_image.n3&data=http://notes.restdesc.org/2011/images/description_images.n3

Your agent executes the resulting instructions

Now, your generic agent has everything it needs to upload an image.
The above result says:
“An HTTP POST request (called _:sk0) to /images/ exists. Its body is myphoto.jpg.
The response to this request is a representation of myphoto.jpg.”
Note how this result is an instantiation of the retrieved description above.

Finally, your client will execute this request, aiming to receive the response.
For this, the only thing your client needs to understand is the HTTP vocabulary.

overview – next

Notes on RESTdesc