HAPI JSON

Hatohol server communicates to plugins by exchanging messages via an AMQP broker. We call the mechanism and the protocol specification HAPI. HAPI supports the following two types of messages:

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

This document describes the latter type: 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. A HAPI plugin developer can use a his/her favorite programming language.

AMQP is a standardized 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 that 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 a 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 ISO 8601 format string},
    "hostName": "${Host name where event is occurred as string}",
    "content": "${Event detail as string}",
    "severity": "${Severity of the event (optional) (default: unknown)}",
    "type": "${Type of the event (optional) (default: bad)}"
  }
}

Here is an example that uses ISO 8601 format for timestamp:

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

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!",
    "severity": "error",
    "type": "bad"
  }
}

severity must be one of the following:

• unknown
• info
• warning
• error
• critical
• emergency

type must be one of the following:

• good
• bad
• unknown