===== API  =====



**NeMo** exposes a simple API that enables you to programmatically get data out of **NeMo** (export), and put data into **NeMo** (import).

In order to effectively use the information in this guide, you need to have an understanding of the **NeMo** functionality and concepts. You should have at least a basic understanding of HTTP/JSON or a
similar programming language, and basic understanding of message queuing method and software.  An understanding of configuring network devices is not required, but may be helpful when actually designing an application using this API.


==== Architecture ====

The method to request or send data to NeMo is to send a JSON message containing the command and related parameters. The output will be a JSON message containing the response to the request.
Users can send messages through two different channels:
  * via HTTP using the script //**api.php**// 
  * via the NeMo message broker that use the AMQP protocol, through the queue "**nemoapi**" 

To test the API messages there is the page apitest.php

This is an example that send the command "hello" to the API module:

<code>
GET api.php HTTP/1.1
HOST: www.nemo.com
Content-Type: application/json

{"token":"1234567890ABCD", "cmd": "hello", "param":{}}
</code>

If everything works fine, the response will be in the form:

<code>
HTTP/1.1 200 OK
Date: Mon, 27 Jul 2009 12:28:53 GMT
Server: Apache/2.2.14
Content-Type: application/json
Connection: Closed
{"success":true,"request":{"cmd":"hello", "param":{}}, "response":{"answer":"hello"}}
</code>

The format of the response JSON is in the form:

<code>
{
   "success": true,   //or false
   "error": "ERROR_CODE", // an error code 
   "message": "a textual message explaining the error", //used only if success=false
   "request": {},  //the JSON received in the request
   "response": {}   //an object containing the response data
}
</code>


==== Authetication ====

NeMo API use JSON Web Token (JWT) as authentication method. The first thing to do is to access the system with a username and password, and then receive a token to use in subsequent requests. The token is valid for 5 minutes from the moment it is issued. 

<code>
{
   "cmd": "login",
   "param": {
       "username": "myuser",
       "password": "mypasswd"
   }
}
</code>

This is a simple response:

<code>
{
   "success":true,
   "request": {
      "cmd":"login",
      "param": { 
          "username":"myuser",
          "password":"mypasswd"
      }
    },
    "response":{
      "token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6IjAiLCJpYXQiOjE0ODUxODE5MDN9.TO4t8OUrRIDxa6mmaEGI8cNkwv5F9vkSdfH_XVNbz5g"
   }
}
</code>


==== Alarms ====

These are the command to use in order to obtain information about alarms.

  * [[#alarmActive|alarmActive]]
  * [[#alarmGet|alarmGet]]
  * [[#alarmMultiget|alarmMultiget]]


=== alarmActive ===

Get all active alarms.

Request:

<code>
{
   "cmd": "alarmActive",
   "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJ...."
   "param": {  }
}
</code>

Response:

<code>
{
   "success": true,
   "request": 
    {
       "cmd": "alarmActive",
       "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJ...."
       "param": {  }
    },
    "response": {
       "responseType": "full",    //valid options: "full", "partial"
       "data": [
          {....},
          {....}
       ]
   }
}
</code>

The "response" object contains the "responseType" field that specify if the content is complete (full) or partial. In case of "partial" response, only the first API_ALARM_MULTIGET_MAXEVENT alarms will be fully provided (if API_ALARM_MULTIGET_MAXEVENT is equal to 0 all messages will be provided in a single response); for the remaining alarms will be provided only the **eventId** field and the client have to call other **alarmGet** or **alarmMultiget** requests to obtain complete information. 
The format for each event elements, is the same as that contained in the [[#alarmGet|alarmGet]] command.

=== alarmGet ===

Request information about a single alarm.

Request:

<code>
{
   "cmd": "alarmGet",
   "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJ...."
   "param": {
      "eventId": 123
   }
}
</code>

Response:

<code>
{
   "success": true,
   "request": 
   {
       "cmd": "alarmGet",
       "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJ...."
       "param": {
          "eventId": 123
       }
    },
    "response":
    {
        eventId: 12345,
        type: 1,
        typeString: “Threshold”,
        deviceId: 1234,
        deviceName: “NODE0101”,
        entityId: 12345,
        thresholdId: 12345,
        description: “DOWN Interface Gi0/1/1.2”
        status: 10,
        statusString: “Active”,
        level: 5,
        levelString: “Critical”,
        start: 1472577290,
        restart: 1472577290,
        end: 0,
        elementInfo: {
	        ifIndex: 23,
	        ifDescr: “GigabitEthernet0/1/1.2”,
	        ifName: “Gi0/1/1.2”,
	        ifType: “Ethernet”,
	        ifAlias: “”,
	        ....
        }
    }
}
</code>


=== alarmMultiget ===

Request information about multiple alarms.

Request:

<code>
{
   "cmd": "alarmMultiget",
   "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJ...."
   "param": {
      "eventIds": [123,234,345,456,567,678,.....]
   }
}
</code>

Response:

<code>
{
   "success": true,
   "request": 
    {
      "cmd": "alarmMultiget",
      "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJ...."
      "param": {
         "eventIds": [123,234,345,456,567,678,.....]
      }
    },
    "response": {
       "responseType": "full",    //valid options: "full", "partial"
       "data": [
          {....},
          {....}
       ]
   }
}
</code>

The "response" object contains the "responseType" field that specify if the content is complete (full) or partial. In case of "partial" response, only the first API_ALARM_MULTIGET_MAXEVENT alarms will be fully provided (if API_ALARM_MULTIGET_MAXEVENT is equal to 0 all messages will be provided in a single response); for the remaining alarms will be provided only the **eventId** field and the client have to call other **alarmGet** or **alarmMultiget** requests to obtain complete information. 
The format for each event elements, is the same as that contained in the [[#alarmGet|alarmGet]] command.



==== Queue ====

These are the command to use in order to manipulate queues.

  * [[#queueLength|queueLength]]
  * [[#queuePurge|queuePurge]]


=== queueLength ===

Request the number of message in a specific queue.

Request:

<code>
{
   "cmd": "queueLength",
   "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJ...."
   "param": {
      "queueName": "fooQueue"
   }
}
</code>

Response:

<code>
{
   "success": true,
   "request": 
    {
      "cmd": "queueLength",
      "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJ...."
      "param": {
         "queueName": "fooQueue"
      }
    },
    "response": {
       "elements": 25,    //number of elements in queue
       "length": 100      //max number of elements (queue dimension)
    }
}
</code>


=== queuePurge ===

Purge the specified queue.

Request:

<code>
{
   "cmd": "queuePurge",
   "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJ...."
   "param": {
      "queueName": "fooQueue"
   }
}
</code>

Response:

<code>
{
   "success": true,
   "request": 
    {
      "cmd": "queuePurge",
      "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJ...."
      "param": {
         "queueName": "fooQueue"
      }
    },
    "response": {}
}
</code>