HAPI JSON

HAPI JSON

In HAPI, Hatohol communicates to plugins via AMQP broker. HAPI and plugins exchange messages via AMQP broker. HAPI supports the following two type messages:

• Hatohol original binary message. ("HAPI Hatohol")
• JSON message. ("HAPI JSON")

This document describes HAPI that uses JSON message. We call HAPI that uses JSON message "HAPI JSON". And we call HAPI that uses Hatohol original binary message "HAPI Hatohol".

Overview

HAPI JSON assumes that HAPI plugin is written by script languages such as Ruby, Pyhon and JavaScript. So HAPI JSON values connectivity. The next sub section describes about connectivity.

HAPI JSON doesn't support sending a request to a plugin. HAPI JSON just receives messages from plugins.

Connectivity

HAPI JSON is more connectable rather than HAPI Hatohol because the following reasons:

• HAPI JSON uses JSON for message format
• HAPI JSON uses AMQP 0-9-1

Most programming languages supports JSON because JSON is a standard format. HAPI plugin developer can use his favorite programming language.

AMQP is a standard protocol. So the protocol itself is connectable. There are some AMQP implementations such as Apache Qpid and RabbitMQ. We can choose an AMQP implementation from some options.

As of 2014, the latest AMQP version is 1.0. 1.0 is incompatible with old versions. And an old version, 0-9-1, is still used widely. Here is a small list of AMQP broker implementation and supported AMQP versions:

• Apache Qpid Java Broker: 1.0, 0-10, 0-9-1, 0-9 and 0-8
• Apache Qpid C++ Broker: 1.0 and 0-10
• RabbitMQ: 0-9-1, 0-9 and 0-8

As of 2014, RabbitMQ is mostly used open source AMQP broker. So most AMQP client libraries use 0-9-1. They can't use AMQP broker that use AMQP 1.0. Most AMQP client libraries will support AMQP 1.0 in the future. But they don't yet for now.

So AMQP 0-9-1 is more connectable rather than AMQP 1.0.

JSON message format

HAPI JSON uses the following JSON message as base format:

{
  "type": "${message type}",
  "body": ${content for the message type}
}

Here are available types:

• event

The following sub sections describes about these types.

event

event type message registers an event to Hatohol.

event type message must has the following format:

{
  "type": "event",
  "body": {
    "id": ${Event ID as an integer},
    "timestamp": ${Event occurred time as UNIX time in float or ISO8601 format string},
    "hostName": "${Host name where event is occurred as string}",
    "content": "${Event detail as string}"
  }
}

Here is an example that uses ISO8601 format for timestamp:

{
  "type": "event",
  "body": {
    "id": 1,
    "timestamp": "2014-08-13T08:29:38Z",
    "hostName": "www.example.com",
    "content": "Web server is down!"
  }
}

Here is an example that uses UNIX time for timestamp. The timestamp value is same as "2014-08-13T08:29:38.803869Z":

{
  "type": "event",
  "body": {
    "id": 1,
    "timestamp": 1407918578.803869,
    "hostName": "www.example.com",
    "content": "Web server is down!"
  }
}