Yggdrasil

A platform for hypermedia multi-agent systems (MAS) (see [1]) built with Vert.x. The current prototype implementation provides two core functionalities:

• it servers as a repository for hypermedia environments that conform to the Agents & Artifacts meta-model [2]

• it acts as a hub that partially implements the W3C WebSub recommendation.

[1] Andrei Ciortea, Olivier Boissier, and Alessandro Ricci. Engineering World-Wide Multi-Agent Systems with Hypermedia. In Engineering Multi-Agent Systems (V. Mascardi, A. Ricci, and D. Weyns,eds.), Springer International Publishing, 2018. To appear.

[2] Alessandro Ricci, Michele Piunti, and Mirko Viroli. Environment Programming in multi-agent systems: an artifact-based perspective. Autonomous Agents and Multi-Agent Systems, 23(2):158{192, Sep 2011.

Prerequisites

• JDK 8+

Building the project

To build the project, just run the default gradle task:

./gradlew

The default Gradle task shadowJar generates a fat-jar in the build/libs directory.

Running Yggdrasil

To start an Yggdrasil node:

java -jar build/libs/emas2018-yggdrasil-0.0-SNAPSHOT-fat.jar -conf src/main/conf/config1.json

The configuration file is optional. Open your browser to http://localhost:8080. You should see an Yggdrasil v0.0 message.

HTTP API Overview

The HTTP API implements CRUD operations for 3 types of resources:

• environments (URI template: /environments/<env_id>)

• workspaces (URI template: /workspaces/<wksp_id>)

• artifacts (URI template: /artifacts/<art_id>)

POST and PUT requests use Turtle payloads (current implementation only validates payload syntax).

POST requests can use the Slug header (see RFC5023) to hint at a preferred IRI for a resource to be created. If the IRI is not already in use, it will be minted to the created resource.

When creating a resource via POST, the resource to be created is identified in the Turtle payload via a null relative IRI:

curl -i -X POST \
  http://localhost:8080/environments/ \
  -H 'content-type: text/turtle' \
  -H 'slug: env1' \
  -d '<> a <http://w3id.org/eve#Environment> ;
<http://w3id.org/eve#contains> <http://localhost:8080/workspaces/wksp1> .'

When retrieving the representation of a resource from Yggdrasil, the HTTP response contains 2 Link headers that clients can use to subscribe for receiving notifications whenever the resource is updated (see the W3C WebSub recommendation). Sample request:

GET /workspaces/wksp1 HTTP/1.1
Host: yggdrasill.andreiciortea.ro

HTTP/1.1 200 OK
Content-Type: text/turtle
Link: <http://yggdrasill.andreiciortea.ro/hub>; rel="hub"
Link: <http://yggdrasill.andreiciortea.ro/workspaces/wksp1>; rel="self"

<http://yggdrasill.andreiciortea.ro/workspaces/wksp1>
  a <http://w3id.org/eve#Workspace> ;
  <http://w3id.org/eve#hasName> "wksp1" ;
  <http://w3id.org/eve#contains>
    <http://85.204.10.233:8080/artifacts/hue1> ,
    <http://yggdrasill.andreiciortea.ro/artifacts/event-gen> .

Using the discovered hub and topic IRIs, a client can subscribe for notification via a POST request that contains a JSON payload with the following fields (see the W3C WebSub recommendation):

• hub.mode

• hub.topic

• hub.callback

When a resource is updated, Yggdrasil issues POST requests with the (updated) resource representation to all registered callbacks.