API Reference

GenieACS expoeses a rich RESTful API through its NBI component. This document serves as a reference for the available APIs.

This API makes use of MongoDB’s query language in some of its endpoints. Refer to MongoDB’s documentation for details.

Note

The examples below use curl command for simplicity and ease of testing. Query parameters are URL-encoded, but the original pre-encoding values are shown for reference. These examples assume genieacs-nbi is running locally and listening on the default NBI port (7557).

Warning

A common pitfll is not properly percent-encoding special characters in the device ID or query in the URL.

Endpoints

GET /<collection>/?query=<query>

Search for records in the database (e.g. devices, tasks, presets, files). Returns a JSON representation of all items in the given collection that match the search criteria.

collection: The data collection to search. Could be one of: tasks, devices, presets, objects.

query: Search query. Refer to MongoDB queries for reference.

Examples

  • Find a device by its ID:
query = {"_id": "202BC1-BM632w-0000000"}
curl -i 'http://localhost:7557/devices/?query=%7B%22_id%22%3A%22202BC1-BM632w-0000000%22%7D'
  • Find a device by its MAC address:
query = {
  "InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANIPConnection.1.MACAddress": "20:2B:C1:E0:06:65"
}
curl -i 'http://localhost:7557/devices/?query=%7B%22InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANIPConnection.1.MACAddress%22%3A%2220:2B:C1:E0:06:65%22%7D'
  • Search for devices that have not initiated an inform in the last 7 days.
query = {
  "_lastInform": {
    "$lt" : "2017-12-11 13:16:23 +0000"
  }
}
curl -i 'http://localhost:7557/devices/?query=%7B%22_lastInform%22%3A%7B%22%24lt%22%3A%222017-12-11%2013%3A16%3A23%20%2B0000%22%7D%7D'
  • Show pending tasks for a given device:
query = {"device": "202BC1-BM632w-0000000"}
curl -i 'http://localhost:7557/tasks/?query=%7B%22device%22%3A%22202BC1-BM632w-0000000%22%7D'
  • Return specific parameters for a given device:
query = {"_id": "202BC1-BM632w-0000000"}
curl -i 'http://localhost:7557/devices?query=%7B%22_id%22%3A%22202BC1-BM632w-0000000%22%7D&projection=InternetGatewayDevice.DeviceInfo.ModelName,InternetGatewayDevice.DeviceInfo.Manufacturer'

The projection URL param is a comma-separated list of the parameters to receive.

POST /devices/<device_id>/tasks?[connection_request]

Enqueue task(s) and optionally trigger a connection request to the device. Refer to Tasks section for information about the task object format. Returns status code 200 if the tasks have been successfully executed, and 202 if the tasks have been queued to be executed at the next inform.

device_id: The ID of the device.

connection_request: Indicates that a connection request will be triggered to execute the tasks immediatly. Otherwise, the tasks will be queued and be processed at the next inform.

The response body is the task object as it is inserted in the database. The object will include _id property which you can use to look up the task later.

Examples

  • Refresh all device parameters now:
curl -i 'http://localhost:7557/devices/202BC1-BM632w-0000000/tasks?connection_request' \
-X POST \
--data '{"name": "refreshObject", "objectName": ""}'
  • Change WiFi SSID and password:
{
  "name": "setParameterValues",
  "parameterValues": [
    ["InternetGatewayDevice.LANDevice.1.WLANConfiguration.1.SSID", "GenieACS", "xsd:string"],
    ["InternetGatewayDevice.LANDevice.1.WLANConfiguration.1.PreSharedKey.1.PreSharedKey", "hello world", "xsd:string"]
  ]
}
curl -i 'http://localhost:7557/devices/202BC1-BM632w-0000000/tasks?connection_request' \
-X POST \
--data '{"name":"setParameterValues", "parameterValues": [["InternetGatewayDevice.LANDevice.1.WLANConfiguration.1.SSID", "GenieACS", "xsd:string"],["InternetGatewayDevice.LANDevice.1.WLANConfiguration.1.PreSharedKey.1.PreSharedKey", "hello world", "xsd:string"]]}'

POST /tasks/<task_id>/retry

Retry a faulty task at the next inform.

task_id: The ID of the task as returned by ‘GET /tasks’ request.

Example

curl -i 'http://localhost:7557/tasks/5403908ef28ea3a25c138adc/retry' -X POST

DELETE /tasks/<task_id>

Delete the given task.

task_id: The ID of the task as returned by ‘GET /tasks’ request.

Example

curl -i 'http://localhost:7557/tasks/5403908ef28ea3a25c138adc' -X DELETE

DELETE /faults/<fault_id>

Delete the given fault.

fault_id: The ID of the fault as returned by ‘GET /faults’ request. The ID format is “<device_id>:<channel>”.

Example

curl -i 'http://localhost:7557/faults/202BC1-BM632w-0000000:default' -X DELETE

DELETE /devices/<device_id>

Delete the given device from the database.

Example

curl -X DELETE -i 'http://localhost:7557/devices/202BC1-BM632w-000001'

Note

Note that the device will be registered again when/if it contacts the ACS again (e.g. on the next periodic inform).

POST /devices/<device_id>/tags/<tag>

Assign a tag to a device. Has no effect if such tag already exists.

device_id: The ID of the device.

tag: The tag to be assigned.

Example

Assign the tag “testing” to a device:

curl -i 'http://localhost:7557/devices/202BC1-BM632w-0000000/tags/testing' -X POST

DELETE /devices/<device_id>/tags/<tag>

Remove a tag from a device.

device_id: The ID of the device.

tag: The tag to be removed.

Example

Remove the tag “testing” from a device:

curl -i 'http://localhost:7557/devices/202BC1-BM632w-0000000/tags/testing' -X DELETE

PUT /presets/<preset_name>

Create or update a preset. Returns status code 200 if the preset has been added/updated successfully. The body of the request is a JSON representation of the preset. Refer to Presets section below for details about its format.

preset_name: The name of the preset.

Example

Create a preset to set 5 minutes inform interval for all devices tagged with “test”:

query = {
  "weight": 0,
  "precondition": "{\"_tags\": \"test\"}"
  "configurations": [
    {
      "type": "value",
      "name": "InternetGatewayDevice.ManagementServer.PeriodicInformEnable",
      "value": "true"
    },
    {
      "type": "value",
      "name": "InternetGatewayDevice.ManagementServer.PeriodicInformInterval",
      "value": "300"
    }
  ]
}
curl -i 'http://localhost:7557/presets/inform' \
-X PUT \
--data '{"weight": 0, "precondition": "{\"_tags\": \"test\"}", "configurations": [{"type": "value", "name": "InternetGatewayDevice.ManagementServer.PeriodicInformEnable", "value": "true"}, {"type": "value", "name": "InternetGatewayDevice.ManagementServer.PeriodicInformInterval", "value": "300"}]}'

DELETE /presets/<preset_name>

curl -i 'http://localhost:7557/presets/inform' -X DELETE

PUT /files/<file_name>

Upload a new file or overwrite an existing one. Returns status code 200 if the file has been added/updated successfully. The file content should be sent as the request body.

file_name: The name of the uploaded file.

The following file metadata may be sent as request headers:

  • fileType: For firmware images it should be “1 Firmware Upgrade Image”. Other common types are “2 Web Content” and “3 Vendor Configuration File”.
  • oui: The OUI of the device model that this file belogs to.
  • productClass: The product class of the device.
  • version: In case of firmware images, this refer to the firmware version.

Example

Upload a firmware image file:

curl -i 'http://localhost:7557/files/new_firmware_v1.0.bin' \
-X PUT \
--data-binary @"./new_firmware_v1.0.bin" \
--header "fileType: 1 Firmware Upgrade Image" \
--header "oui: 123456" \
--header "productClass: ABC" \
--header "version: 1.0"

DELETE /files/<file_name>

Delete a previously uploaded file:

curl -i 'http://localhost:7557/files/new_firmware_v1.0.bin' -X DELETE

GET /files/

Gets all previously uploaded files.

GET /files/?query={“filename”:”<filename>”}

Find files using a query.

Tasks

Find the different availabe tasks and their object structure.

getParameterValues

query = {
  "name": "getParameterValues",
  "parameterNames": [
    "InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANIPConnectionNumberOfEntries",
    "InternetGatewayDevice.Time.NTPServer1", "InternetGatewayDevice.Time.Status"
  ]
}
curl -i 'http://localhost:7557/devices/00236a-96318REF-SR360NA0A4%252D0003196/tasks?timeout=3000&connection_request' \
-X POST \
--data '{"name": "getParameterValues", "parameterNames": ["InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANIPConnectionNumberOfEntries", "InternetGatewayDevice.Time.NTPServer1", "InternetGatewayDevice.Time.Status"] }'

You may request a single or multiple parameters at once.

After the task has been executed successfully you can then fetch the CPE object and read the parameters from the JSON object.

query = {"_id": "00236a-96318REF-SR360NA0A4%2D0003196"}
curl -i 'http://localhost:7557/devices/?query=%7B%22_id%22%3A%2200236a-96318REF-SR360NA0A4%252D0003196%22%7D'

refreshObject

curl -i 'http://localhost:7557/devices/00236a-SR552n-SR552NA084%252D0003269/tasks?timeout=3000&connection_request' \
-X POST \
--data '{"name": "refreshObject", "objectName": "InternetGatewayDevice.WANDevice.1.WANConnectionDevice"}'

setParameterValues

curl -i 'http://localhost:7557/devices/00236a-SR552n-SR552NA084%252D0003269/tasks?timeout=3000&connection_request' \
-X POST \
--data '{"name": "setParameterValues", "parameterValues": [["InternetGatewayDevice.ManagementServer.UpgradesManaged",false]]}'

Multiple values can be set at once by adding multiple arrays to the parameterValues key. For example:

{
  name: "setParameterValues",
  parameterValues: [["InternetGatewayDevice.ManagementServer.UpgradesManaged", false], ["InternetGatewayDevice.Time.Enable", true], ["InternetGatewayDevice.Time.NTPServer1", "pool.ntp.org"]]
}

addObject

curl -i 'http://localhost:7557/devices/00236a-SR552n-SR552NA084%252D0003269/tasks?timeout=3000&connection_request' \
-X POST \
--data '{"name":"addObject","objectName":"InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANPPPConnection"}'

deleteObject

curl -i 'http://localhost:7557/devices/00236a-SR552n-SR552NA084%252D0003269/tasks?timeout=3000&connection_request' \
-X POST \
--data '{"name":"deleteObject","objectName":"InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANPPPConnection.1"}'

reboot

curl -i 'http://localhost:7557/devices/00236a-SR552n-SR552NA084%252D0003269/tasks?timeout=3000&connection_request' \
-X POST \
--data '{"name": "reboot"}'

factoryReset

curl -i 'http://localhost:7557/devices/00236a-SR552n-SR552NA084%252D0003269/tasks?timeout=3000&connection_request' \
-X POST \
--data '{"name": "factoryReset"}'

download

curl -i 'http://localhost:7557/devices/00236a-SR552n-SR552NA084%252D0003269/tasks?timeout=3000&connection_request' \
-X POST \
--data '{"name": "download", "file": "mipsbe-6-42-lite.xml"}'

Presets

Presets assign a set of configuration or a Provision script to devices based on a precondition (search filter), schedule (cron expression), and events.

Precondition

The precondition property is a JSON string representation of the search filter to test if the preset applies to a given device. Examples preconditions are:

  • {"param": "value"}
  • {"param": value", "param2": {"$ne": "value2"}}

Other operators that can be used are $gt, $lt, $gte and $lte.

Configuration

The configuration property is an array containing the different configurations to be applied to a device, as shown below:

[
  {
    "type": "value",
    "name": "InternetGatewayDevice.ManagementServer.PeriodicInformEnable",
    "value": "true"
  },
  {
    "type": "value",
    "name": "InternetGatewayDevice.ManagementServer.PeriodicInformInterval",
    "value": "300"
  },
  {
    "type": "delete_object",
    "name": "object_parent",
    "object": "object_name"
  },
  {
    "type": "add_object",
    "name": "object_parent",
    "object": "object_name"
  },
  {
    "type": "provision",
    "name": "YourProvisionName"
  },
]

The configuration type provision triggers a Provision script. In the example above, the provision named “YourProvisionName” will be executed.

Provisions

Create a provision

The Provision’s JavaScript code is the body of the HTTP PUT request.

curl -X PUT -i 'http://localhost:7557/provisions/mynewprovision' --data 'log("Provision started at " + now);'

Delete a provision

curl -X DELETE -i 'http://localhost:7557/provisions/mynewprovision'

Get provisions

Get all provisions:

curl -X GET -i 'http://localhost:7557/provisions/'