Group

>>>

GET /api/v2/groups
List all groups

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

Params

Param name Description
page
optional

Page number of results to be fetched, Default 1


Value: Must be Integer.
per
optional

Number of group records to be returned in one page, Default 20


Value: Must be Integer.
order_by
optional

Field on which resultant group records 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
timestamp_format
optional

Format, “str” or “int”, in which timestamps of the group records should be returned, Default “int”


Value: Must be a String
search
optional

Keywords based on which groups should be searched. Currently you can search groups on - group_key, name or tag


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
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 groups without any criteria
  curl -X GET -H "Content-Type:application/json" -H "X-Auth-Token:-Jt7v9qpdq8Ivi1WwQ6_iQ" https://api.datonis.io/api/v2/groups

Response (returns first 20 records)
{
  "total_count": 4,
  "page": 1,
  "groups": [
    {
      "created_at": 1428569250,
      "updated_at": 1417064371,
      "description": "",
      "group_key": "8tt9t7dde4",
      "name": "Energy Meters Single Phase 30Amps",
      "scope": "all",
      "tags_array": [
        "1-Phase",
        "30-Amps"
      ],
      "tags": "1-Phase,30-Amps"
    },
    {
      "created_at": 1428569273,
      "updated_at": 1417064371,
      "description": "",
      "group_key": "79t199fa1d",
      "name": "Energy Meters Single Phase 15Amps",
      "scope": "all",
      "tags_array": [
        "1-Phase",
   ...
Request - listing groups by specifying number of groups 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:-Jt7v9qpdq8Ivi1WwQ6_iQ" -d '{"per":"2","page":"2"}' https://api.datonis.io/api/v2/groups

Response (returns page 2 with 2 groups per page)
{
  "total_count": 4,
  "page": "2",
  "groups": [
    {
      "created_at": 1428569310,
      "updated_at": 1417064371,
      "description": "",
      "group_key": "t5cet45336",
      "name": "Energy Meters Three Phase 30Amps",
      "scope": "all",
      "tags_array": [
        "3-Phase",
        "30-Amps"
      ],
      "tags": "3-Phase,30-Amps"
    },
    {
      "created_at": 1428569337,
      "updated_at": 1417064371,
      "description": "",
      "group_key": "2abebc5edt",
      "name": "Energy Meters Three Phase 60Amps",
      "scope": "all",
      "tags_array": [
        "3-Phase",
   ...
Request - listing groups ordered by a field with string formatted timestamps
  curl -X GET -H "Content-Type:application/json" -H "X-Auth-Token:-Jt7v9qpdq8Ivi1WwQ6_iQ" -d '{"timestamp_format":"str","order_by":"created_at","order":"desc"}' https://api.datonis.io/api/v2/groups

Response (returns groups in the reverse order of time that they were created at with timestamps in string format)
{
  "total_count": 4,
  "page": 1,
  "groups": [
    {
      "created_at": "2014/11/26 11:26:42",
      "updated_at": "2014/11/27 04:59:31",
      "description": "",
      "group_key": "2abebc5edt",
      "name": "Energy Meters Three Phase 60Amps",
      "scope": "all",
      "tags_array": [
        "3-Phase",
        "60-Amps"
      ],
      "tags": "3-Phase,60-Amps"
    },
    {
      "created_at": "2015/04/09 08:48:30",
      "updated_at": "2014/11/27 04:59:31",
      "description": "",
      "group_key": "t5cet45336",
      "name": "Energy Meters Three Phase 30Amps",
      "scope": "all",
  ...
Request - listing groups based on some search criteria with all keywords matching
  curl -X GET -H "Content-Type:application/json" -H "X-Auth-Token:-Jt7v9qpdq8Ivi1WwQ6_iQ" -d '{"search":"Single 30Amps"}' https://api.datonis.io/api/v2/groups

Response (returns groups containing both keywords 'Single' as well as '30Amps')
{
  "total_count": 1,
  "page": 1,
  "groups": [
    {
      "created_at": 1428569250,
      "updated_at": 1417064371,
      "description": "",
      "group_key": "8tt9t7dde4",
      "name": "Energy Meters Single Phase 30Amps",
      "scope": "all",
      "tags_array": [
        "1-Phase",
        "30-Amps"
      ],
      "tags": "1-Phase,30-Amps"
    }
  ]
}
Request - listing groups based on some search criteria with any of the keywords matching
  curl -X GET -H "Content-Type:application/json" -H "X-Auth-Token:-Jt7v9qpdq8Ivi1WwQ6_iQ" -d '{"search":"Single 30Amps", "scope":"any"}' https://api.datonis.io/api/v2/groups

Response (returns groups containing either of the keywords 'Single' or '30Amps')
{
  "total_count": 3,
  "page": 1,
  "groups": [
    {
      "created_at": 1428569250,
      "updated_at": 1417064371,
      "description": "",
      "group_key": "8tt9t7dde4",
      "name": "Energy Meters Single Phase 30Amps",
      "scope": "all",
      "tags_array": [
        "1-Phase",
        "30-Amps"
      ],
      "tags": "1-Phase,30-Amps"
    },
    {
      "created_at": 1428569273,
      "updated_at": 1417064371,
      "description": "",
      "group_key": "79t199fa1d",
      "name": "Energy Meters Single Phase 15Amps",
      "scope": "all",
      "tags_array": [
        "1-Phase",
        "15-Amps"
      ],
      "tags": "1-Phase,15-Amps"
    },
    {
      "created_at": 1428569310,
      "updated_at": 1417064371,
     ...
>>>

GET /api/v2/groups/:group_key
Fetch details of a specific group

Returns details of the group specified

Params

Param name Description
pretty
optional

Return a pretty formatted response if true, Default is false


Value: Must be a Boolean

Examples

Request - get details of the specified group (group_key specified as a part of the url)
  curl -X GET -H "Content-Type:application/json" -H "X-Auth-Token:-Jt7v9qpdq8Ivi1WwQ6_iQ" https://api.datonis.io/api/v2/groups/8tt9t7dde4

Response (details of the group requested)
{
  "group": {
    "description": "",
    "group_key": "8tt9t7dde4",
    "name": "Energy Meters Single Phase 30Amps",
    "scope": "all",
    "tags_array": [
      "1-Phase",
      "30-Amps"
    ],
    "tags": "1-Phase,30-Amps",
    "created_at": 1428569250,
    "updated_at": 1417064371
  }
}
>>>

POST /api/v2/groups
Create a group

Creates a group with given parameters

Params

Param name Description
group
required

Object containing information about the group 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:-Jt7v9qpdq8Ivi1WwQ6_iQ" -d '{"group":{"name":"Energy Meters Three Phase 45Amps","description":"Energy Meters Three Phase 45Amps","scope":"all","tags":"3-Phase,45-Amps"}}' https://api.datonis.io/api/v2/groups

Response (details of the group created)
{
  "group": {
    "description": "Energy Meters Three Phase 45Amps",
    "group_key": "9522a7a16t",
    "name": "Energy Meters Three Phase 45Amps",
    "scope": "all",
    "tags_array": [
      "3-Phase",
      "45-Amps"
    ],
    "tags": "3-Phase,45-Amps",
    "created_at": 1428587904,
    "updated_at": 1417064371
  }
}
>>>

PUT /api/v2/groups/:group_key
Updates a group

Updates the group with given parameters

Params

Param name Description
group
required

Object containing information about the group 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 - containing parameters to be modified
  curl -X PUT -H "Content-Type:application/json" -H "X-Auth-Token:-Jt7v9qpdq8Ivi1WwQ6_iQ" -d '{"group":{"name":"Energy Meters Three Phase 50Amps","description":"Energy Meters Three Phase 50Amps","tags":"3-Phase,50-Amps"}}' https://api.datonis.io/api/v2/groups/9522a7a16t

Response (details of the group updated)
{
  "group": {
    "description": "Energy Meters Three Phase 50Amps",
    "group_key": "9522a7a16t",
    "name": "Energy Meters Three Phase 50Amps",
    "scope": "all",
    "tags_array": [
      "3-Phase",
      "50-Amps"
    ],
    "tags": "3-Phase,50-Amps",
    "created_at": 1428587904,
    "updated_at": 1417064371
  }
}
>>>

DELETE /api/v2/groups/:group_key
Delete the specified group

Deletes the specified group 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:-Jt7v9qpdq8Ivi1WwQ6_iQ"  https://api.datonis.io/api/v2/groups/9522a7a16t

Response
{
}
>>>

PUT /api/v2/groups/:group_key/tag
Add specified tags to a group

Adds specified tags to the existing list of tags associated with the group

Params

Param name Description
tags
optional

Comma separated list of tags to be added to the group


Value: Must be a String
pretty
optional

Return a pretty formatted response if true, Default is false


Value: Must be a Boolean

Examples

Request - add tags to the specified group (group_key specified as a part of the url)
  curl -X PUT -H "Content-Type:application/json" -H "X-Auth-Token:-Jt7v9qpdq8Ivi1WwQ6_iQ" -d '{"tags":"4-Wire,Balanced"}' https://api.datonis.io/api/v2/groups/8tt9t7dde4/tag

Response (group with updated tags)
{
  "group": {
    "description": "",
    "group_key": "8tt9t7dde4",
    "name": "Energy Meters Single Phase 30Amps",
    "scope": "all",
    "tags_array": [
      "1-Phase",
      "30-Amps",
      "4-Wire",
      "Balanced"
    ],
    "tags": "1-Phase,30-Amps,4-Wire,Balanced",
    "created_at": 1428569250,
    "updated_at": 1417064371
  }
}
>>>

PUT /api/v2/groups/:group_key/untag
Remove specified tags from the group

Removes specified tags from the group

Params

Param name Description
tags
optional

Comma separated list of tags to be removed from the group


Value: Must be a String
pretty
optional

Return a pretty formatted response if true, Default is false


Value: Must be a Boolean

Examples

Request - remove tags from the specified group (group_key specified as a part of the url)
  curl -X PUT -H "Content-Type:application/json" -H "X-Auth-Token:-Jt7v9qpdq8Ivi1WwQ6_iQ" -d '{"tags":"4-Wire,Balanced"}' https://api.datonis.io/api/v2/groups/8tt9t7dde4/untag

Response (group with updated tags)
{
  "group": {
    "description": "",
    "group_key": "8tt9t7dde4",
    "name": "Energy Meters Single Phase 30Amps",
    "scope": "all",
    "tags_array": [
      "1-Phase",
      "30-Amps"
    ],
    "tags": "1-Phase,30-Amps",
    "created_at": 1428569250,
    "updated_at": 1417064371
  }
}