Instruction

>>>

GET /api/v2/instructions
List all instructions

Returns a list of all instructions belonging to an account as per the specified criteria. This API is paginated and returns 20 instructions by default. An instruction is uniquely identified by an 'instruction_key'. This key should be used in all the other API referencing a particular instruction.

Params

Param name Description
page
optional

Page number of results to be fetched, Default 1


Value: Must be Integer.
per
optional

Number of instructions to be returned in one page, Default 20


Value: Must be Integer.
order_by
optional

Field on which instructions should be sorted


Value: Must be a String
order
optional

Order, “asc” or “desc”, in which results should be sorted


Value: Must be a String
search
optional

Keywords based on which instructions should be searched. Currently you can search instructions on - instruction_key, name or definition


Value: Must be a String
scope
optional

Matching condition if multiple keywords are specified for search. Valid values are “all” or “any”. Default is “all”


Value: Must be a String
timestamp_format
optional

Format, “str” or “int”, in which timestamps should be returned, Default “int”


Value: Must be a String
pretty
optional

Return a pretty formatted response if true, Default is false


Value: Must be a Boolean
field_list
optional

List of fields required in the result.


Value: Must be an array of any type

Examples

Request - listing all instructions without any criteria
  curl -X GET -H "Content-Type:application/json" -H "X-Auth-Token:olezAZXGQn9MutnfNerKDQ" https://api.datonis.io/api/v2/instructions

Response (returns first 20 records)
{
  "total_count": 7,
  "page": 1,
  "instructions": [
    {
      "created_at": 1425297763,
      "updated_at": 1425297763,
      "definition": {
        "status": "on"
      },
      "description": "",
      "instruction_key": "a5ad49t441",
      "name": "Start Machine"
    },
    {
      "created_at": 1425297763,
      "updated_at": 1425297763,
      "definition": {
        "status": "off"
      },
      "description": "",
      "instruction_key": "6aa487t8at",
      "name": "Stop Machine"
    },
    {
      "created_at": 1425297763,
      "updated_at": 1425297763,
      "definition": [
        {
          "status": "off"
        },
        {
          "status": "on"
        }
      ],
      "description": "",
      "instruction_key":...
Request - listing instructions by specifying number of instructions to be returned at a time (page size) and specific set to be returned (page)
  curl -X GET -H "Content-Type:application/json" -H "X-Auth-Token:olezAZXGQn9MutnfNerKDQ" -d '{"per":"2","page":"2"}' https://api.datonis.io/api/v2/instructions

Response (returns page 2 with 2 instructions per page)
{
  "total_count": 7,
  "page": "2",
  "instructions": [
    {
      "created_at": 1425297763,
      "updated_at": 1425297763,
      "definition": [
        {
          "status": "off"
        },
        {
          "status": "on"
        }
      ],
      "description": "",
      "instruction_key": "t3e62tact4",
      "name": "Restart Machine"
    },
    {
      "created_at": 1425297763,
      "updated_at": 1425297763,
      "definition": {
        "add_pressure": 10
      },
      "description": "",
      "instruction_key": "71f2fc1ab7",
      "name": "Increase Pressure 10 PSI"
    }
  ]
}
Request - listing instructions ordered by a field
  curl -X GET -H "Content-Type:application/json" -H "X-Auth-Token:olezAZXGQn9MutnfNerKDQ" -d '{"order_by":"name","order":"desc"}' https://api.datonis.io/api/v2/instructions

Response (returns instructions in the reverse order of their name)
{
  "total_count": 7,
  "page": 1,
  "instructions": [
    {
      "created_at": 1425297763,
      "updated_at": 1425297763,
      "definition": {
        "lock_status": "unlocked"
      },
      "description": "",
      "instruction_key": "966c9c6t5f",
      "name": "Unlock"
    },
    {
      "created_at": 1425297763,
      "updated_at": 1425297763,
      "definition": {
        "status": "off"
      },
      "description": "",
      "instruction_key": "6aa487t8at",
      "name": "Stop Machine"
    },
    {
      "created_at": 1425297763,
      "updated_at": 1425297763,
      "definition": {
        "status": "on"
      },
      "description": "",
      "instruction_key": "a5ad49t441",
      "name": "Start Machine"
    },
    {
     ...
Request - listing instructions based on some search criteria with all keywords matching
  curl -X GET -H "Content-Type:application/json" -H "X-Auth-Token:olezAZXGQn9MutnfNerKDQ" -d '{"search":"start machine"}' https://api.datonis.io/api/v2/instructions

Response (returns instructions containing both keywords 'start' as well as 'machine')
{
  "total_count": 2,
  "page": 1,
  "instructions": [
    {
      "created_at": 1425297763,
      "updated_at": 1425297763,
      "definition": {
        "status": "on"
      },
      "description": "",
      "instruction_key": "a5ad49t441",
      "name": "Start Machine"
    },
    {
      "created_at": 1425297763,
      "updated_at": 1425297763,
      "definition": [
        {
          "status": "off"
        },
        {
          "status": "on"
        }
      ],
      "description": "",
      "instruction_key": "t3e62tact4",
      "name": "Restart Machine"
    }
  ]
}
Request - listing instructions based on some search criteria with any of the keywords matching
  curl -X GET -H "Content-Type:application/json" -H "X-Auth-Token:olezAZXGQn9MutnfNerKDQ" -d '{"search":"start machine", "scope":"any"}' https://api.datonis.io/api/v2/instructions

Response (returns instructions containing either of the keywords 'start' or 'machine')
{
  "total_count": 3,
  "page": 1,
  "instructions": [
    {
      "created_at": 1425297763,
      "updated_at": 1425297763,
      "definition": {
        "status": "on"
      },
      "description": "",
      "instruction_key": "a5ad49t441",
      "name": "Start Machine"
    },
    {
      "created_at": 1425297763,
      "updated_at": 1425297763,
      "definition": {
        "status": "off"
      },
      "description": "",
      "instruction_key": "6aa487t8at",
      "name": "Stop Machine"
    },
    {
      "created_at": 1425297763,
      "updated_at": 1425297763,
      "definition": [
        {
          "status": "off"
        },
        {
          "status": "on"
        }
      ],
      "description": "",
      "instruction_key": "t3e62tact4",
      "name": "Restart Machine"
    }
  ]
}
>>>

POST /api/v2/instructions
Create an instruction

Creates an instruction with given parameters

Params

Param name Description
instruction
required

Map containing details of the instruction to be created


Value: Must be a Hash
pretty
optional

Return a pretty formatted response if true, Default is false


Value: Must be a Boolean

Examples

Request
  curl -X POST -H "Content-Type:application/json" -H "X-Auth-Token:olezAZXGQn9MutnfNerKDQ"  -d '{"instruction":{"name":"Increase Pressure 20 PSI","definition":{"add_pressure":20},"description":"Increases pressure by 20 PSI"}}' https://api.datonis.io/api/v2/instructions

Response (containing details of the instruction created)
{
  "instruction": {
    "created_at": 1425297763,
    "updated_at": 1425297763,
    "definition": {
      "add_pressure": 20
    },
    "description": "Increases pressure by 20 PSI",
    "instruction_key": "2bbdt86783",
    "name": "Increase Pressure 20 PSI"
  }
}
>>>

GET /api/v2/instructions/:instruction_key
Fetch an instruction

Get details of an instruction

Params

Param name Description
pretty
optional

Return a pretty formatted response if true, Default is false


Value: Must be a Boolean

Examples

Request
  curl -X GET -H "Content-Type:application/json" -H "X-Auth-Token:olezAZXGQn9MutnfNerKDQ"  https://api.datonis.io/api/v2/instructions/2bbdt86783

Response (containing details of the instruction)
{
  "instruction": {
    "created_at": 1425297763,
    "updated_at": 1425297763,
    "definition": {
      "add_pressure": 20
    },
    "description": "Increases pressure by 20 PSI",
    "instruction_key": "2bbdt86783",
    "name": "Increase Pressure 20 PSI"
  }
}
>>>

PUT /api/v2/instructions/:instruction_key
Update an instruction

Updates an instruction with given parameters

Params

Param name Description
instruction
required

Map containing details of the instruction to be updated


Value: Must be a Hash
pretty
optional

Return a pretty formatted response if true, Default is false


Value: Must be a Boolean

Examples

Request
  curl -X PUT -H "Content-Type:application/json" -H "X-Auth-Token:olezAZXGQn9MutnfNerKDQ"  -d '{"instruction":{"name":"Increase Pressure 30 PSI","definition":{"add_pressure":30},"description":"Increases pressure by 30 PSI"}}' https://api.datonis.io/api/v2/instructions/2bbdt86783

Response (containing details of the instruction updated)
{
  "instruction": {
    "created_at": 1425297763,
    "updated_at": 1425297763,
    "definition": {
      "add_pressure": 30
    },
    "description": "Increases pressure by 30 PSI",
    "instruction_key": "2bbdt86783",
    "name": "Increase Pressure 30 PSI"
  }
}
>>>

DELETE /api/v2/instructions/:instruction_key
Delete an instruction

Deletes an instruction from the system

Params

Param name Description
pretty
optional

Return a pretty formatted response if true, Default is false


Value: Must be a Boolean

Examples

Request
  curl -X DELETE -H "Content-Type:application/json" -H "X-Auth-Token:olezAZXGQn9MutnfNerKDQ"  https://api.datonis.io/api/v2/instructions/2bbdt86783

Response
{
}
>>>

PUT /api/v2/instructions/:instruction_key/execute
Execute an instruction

Executes the specified instruction against given input objects

Params

Param name Description
instruction_applicability
required

Whether to execute an instruction on:

2: sensors of a particular type
3: specified sensors

Value: Must be Integer.
instruction_applicability_value
required

sensor type or a sensor_key or an array of sensor keys depending on the value of instruction_applicability
pretty
optional

Return a pretty formatted response if true, Default is false


Value: Must be a Boolean

Examples

Request - execute an instruction against all sensors of type 'Energy Meter'
  curl -X PUT -H "Content-Type:application/json" -H "X-Auth-Token:olezAZXGQn9MutnfNerKDQ" -d '{"instruction_applicability":"2","instruction_applicability_value":"Energy Meter"}' https://api.datonis.io/api/v2/instructions/a5ad49t441/execute

Response (list of sensor alert keys describing execution status of the instruction against each sensor)
{
  "status": [
    "7c1fb74f57",
    "8e13bf7517"
  ]
}
Request - execute an instruction against specified sensors
  curl -X PUT -H "Content-Type:application/json" -H "X-Auth-Token:olezAZXGQn9MutnfNerKDQ" -d '{"instruction_applicability":"3","instruction_applicability_value":["16dc891e4b255735d7tafete13e6fdc412628t84","27ce8667143fa217b3eb9ecbedcbacdc28addt97"]}' https://api.datonis.io/api/v2/instructions/a5ad49t441/execute

Response (list of sensor alert keys describing execution status of the instruction against each sensor)
{
  "status": [
    "2577aaf9t6",
    "7a78ae52c8"
  ]
}