Simply describe functionality.

Functionality captures the essentials of APIs, and RESTdesc aims to describe this. Resources and their hyperlinks make up the cornerstones of descriptions.

Describe the meaning of hypermedia links.

By hypermedia APIs, we mean REST APIs or RESTful services, in their original meaning defined by Roy T. Fielding. They have two important characteristics:

• resource-orientedness: every URI represents a resource.
• hypermedia-driven: hypermedia links indicate where to go from a resource.

For example, suppose you have a photo that has a thumbnail link.
The photo is thus a resource, and the link tells you what you can do with it.
You know what this link brings, since you understand the concept "thumbnail".

Machines, however, are unable to predict where a link will lead.
Therefore, RESTdesc explains what it means to follow a specific link.

RESTdesc connects hyperlinks to functionality.

A RESTdesc description of a thumbnail link might look like this:

@prefix : <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 :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 consists of three parts, stating:
if your image has a smallThumbnail link to a resource
then there exists a GET request to that resource, resulting in a response
that will be an 80 pixels high thumbnail of your image.

With this description, an agent can understand what a smallThumbnail links means and therefore autonomously decide whether it should follow this link.

Elegant reuse helps the Web forward.

The above example shows the important characteristics of RESTdesc:

Vocabulary reuse

You as a description author can choose the vocabulary of your preference, such as dbpedia or dbpedia-owl. RESTdesc doesn't enforce any vocabulary of its own, but reuses the HTTP vocabulary.

Technology reuse

You don't need to learn a new language or find new tools, since RESTdesc descriptions are expressed in Notation3 or N3, a small superset of RDF. Existing N3 tools are fully compatible with RESTdesc by design.

Compactness and elegance

You only write what clients really use. Additional information is retrieved when necessary: for example, the meaning of thumbnail and height are defined in DBpedia.

Not only is RESTdesc capable of fluently capturing functionality, it also provides the mechanisms to discover it.

The above example in more detail can be found in the image API use case, which also features other types of descriptions, such as a POST example.