Groups#

Auth service#

For grouping Mainflux entities there are groups object in the auth service. Grouping of entities can be done for things and users but additionally you can use groups for grouping some external entities as well. Groups are organized like a tree, group can have one parent and children. Group with no parent is root of the tree.

Create a group#

curl -is -S -X POST http://localhost/groups -d '{"name":"<group_name>","description":"<group_description>","parent_id":"<parent_id>","metadata":<group_metadata>}' -H 'Content-Type: application/json' -H "Authorization: $TOK"                    
HTTP/1.1 201 Created
Server: nginx/1.16.0
Date: Fri, 09 Apr 2021 08:02:02 GMT
Content-Type: application/json
Content-Length: 0
Connection: keep-alive
Location: /groups/01F2TTDYGMP6DW083NE6E0DKH2
Access-Control-Expose-Headers: Location

• group_name - name of the group
• group_description - description of group up to 1024 characters.
• parent_id - id of parent group, if not specified created group is tree root.
• metadata - custom metadata that can be attached to group object for specific application needs.

Fetch a group#

curl -s -S -X GET http://localhost/groups/01F2TTDYGMP6DW083NE6E0DKH2 -H "Authorization: $TOK" 

Create a child#

curl -is -S -X POST http://localhost/groups -d '{"name":"test1","description":"<group_description>","parent_id":"01F2TTDYGMP6DW083NE6E0DKH2","metadata":{"group_attr":"attr_value"}}' -H 'Content-Type: application/json' -H "Authorization: $TOK" 
HTTP/1.1 201 Created
Server: nginx/1.16.0
Date: Fri, 09 Apr 2021 08:09:37 GMT
Content-Type: application/json
Content-Length: 0
Connection: keep-alive
Location: /groups/01F2TTVV5NJH63FE5KXMNPWB8P
Access-Control-Expose-Headers: Location

Fetch a child group#

curl -s -S -X GET http://localhost/groups/01F2TTVV5NJH63FE5KXMNPWB8P -H "Authorization: $TOK" | jq
{
  "id": "01F2TTVV5NJH63FE5KXMNPWB8P",
  "name": "test1",
  "owner_id": "8e968002-1b19-4e17-bfb6-f0064888a2d1",
  "parent_id": "01F2TTDYGMP6DW083NE6E0DKH2",
  "description": "group for test",
  "metadata": {
    "group_attr": "attr_value"
  },
  "level": 1,
  "created_at": "2021-04-09T08:09:37.718Z",
  "updated_at": "2021-04-09T08:09:37.718Z"
}

• owner_id - is attached by service, it is id of the user that issued create request.
• level - is generated by service, it represents a level in a tree hierarchy
• created_at - time of creation, generated by service.
• updated_at - time of update, generated by service.

Fetch group hierarchy#

To fetch a group hierarchy you can either fetch children for a group or a direct ascendant line

Fetch a parent#

 curl -s -S -X GET http://localhost/groups/<group_id>/parents?tree=true&level=5 -H "Authorization: <auth_token>" | jq
{
  "total": 2,
  "level": 1,
  "name": "",
  "groups": [
    {
      "id": "01F2TTDYGMP6DW083NE6E0DKH2",
      "name": "test",
      "owner_id": "8e968002-1b19-4e17-bfb6-f0064888a2d1",
      "description": "group for test",
      "metadata": {
        "group_attr": "attr_value"
      },
      "level": 1,
      "path": "01F2TTDYGMP6DW083NE6E0DKH2",
      "children": [
        {
          "id": "01F2TTVV5NJH63FE5KXMNPWB8P",
          "name": "test1",
          "owner_id": "8e968002-1b19-4e17-bfb6-f0064888a2d1",
          "parent_id": "01F2TTDYGMP6DW083NE6E0DKH2",
          "description": "group for test",
          "metadata": {
            "group_attr": "attr_value"
          },
          "level": 2,
          "path": "01F2TTDYGMP6DW083NE6E0DKH2.01F2TTVV5NJH63FE5KXMNPWB8P",
          "created_at": "2021-04-09T08:09:37.718Z",
          "updated_at": "2021-04-09T08:09:37.718Z"
        }
      ],
      "created_at": "2021-04-09T08:02:02.389Z",
      "updated_at": "2021-04-09T08:02:02.389Z"
    }
  ]
}

• tree - if true response is JSON that represent a groups tree structure. If ommited or false than groups will be retrieve as list
• level - limits the hierarchy to be retrieved. Max level to be fetched in one request is 5.

Fetch children#

curl -s -S -X GET http://localhost/groups/01F2TTDYGMP6DW083NE6E0DKH2/children\?tree\=true\&level\=5 -H "Authorization: $TOK" | jq
{
  "total": 3,
  "level": 5,
  "name": "",
  "groups": [
    {
      "id": "01F2TTDYGMP6DW083NE6E0DKH2",
      "name": "test",
      "owner_id": "8e968002-1b19-4e17-bfb6-f0064888a2d1",
      "description": "group for test",
      "metadata": {
        "group_attr": "attr_value"
      },
      "level": 1,
      "path": "01F2TTDYGMP6DW083NE6E0DKH2",
      "children": [
        {
          "id": "01F2TTVV5NJH63FE5KXMNPWB8P",
          "name": "test1",
          "owner_id": "8e968002-1b19-4e17-bfb6-f0064888a2d1",
          "parent_id": "01F2TTDYGMP6DW083NE6E0DKH2",
          "description": "group for test",
          "metadata": {
            "group_attr": "attr_value"
          },
          "level": 2,
          "path": "01F2TTDYGMP6DW083NE6E0DKH2.01F2TTVV5NJH63FE5KXMNPWB8P",
          "created_at": "2021-04-09T08:09:37.718Z",
          "updated_at": "2021-04-09T08:09:37.718Z"
        },
        {
          "id": "01F2TTJPXSZ7K941T57MX3V03M",
          "name": "test",
          "owner_id": "8e968002-1b19-4e17-bfb6-f0064888a2d1",
          "parent_id": "01F2TTDYGMP6DW083NE6E0DKH2",
          "description": "group for test",
          "metadata": {
            "group_attr": "attr_value"
          },
          "level": 2,
          "path": "01F2TTDYGMP6DW083NE6E0DKH2.01F2TTJPXSZ7K941T57MX3V03M",
          "created_at": "2021-04-09T08:04:38.458Z",
          "updated_at": "2021-04-09T08:04:38.458Z"
        }
      ],
      "created_at": "2021-04-09T08:02:02.389Z",
      "updated_at": "2021-04-09T08:02:02.389Z"
    }
  ]
}

Assign a member to a group#

You can assign members to a group by putting entity ids into a group For example assigning users to a group

curl -isSX POST http://localhost/groups/<group_id>/members -d '{"members":["<user_id1>",..."<user_idN>"],"type":"users"}' -H "Authorization: $TOK" -H 'Content-Type: application/json'
HTTP/1.1 200 OK
Server: nginx/1.16.0
Date: Fri, 09 Apr 2021 09:40:35 GMT
Content-Type: application/json
Content-Length: 0
Connection: keep-alive
Access-Control-Expose-Headers: Location

Or assigning things to a group

curl -isSX POST http://localhost/groups/01F2TTDYGMP6DW083NE6E0DKH2/members -d '{"members":["a0b1d516-67c6-4e8d-8ea2-ad4aff444ca3","9a036414-5d47-4122-9e58-b3b6953a2097"],"type":"things"}' -H "Authorization: $TOK" -H 'Content-Type: application/json'
HTTP/1.1 200 OK
Server: nginx/1.16.0
Date: Fri, 09 Apr 2021 09:43:24 GMT
Content-Type: application/json
Content-Length: 0
Connection: keep-alive
Access-Control-Expose-Headers: Location

To fetch members you can use endpoint on auth, things or users service. Endpoint on auth service only retrieves member ids. Endpoints on things and users will retrieve full objects.

Fetching members#

Fetching from auth service#

curl -sSX GET http://localhost/groups/01F2TTDYGMP6DW083NE6E0DKH2/members  -H "Authorization: $TOK" | jq
{
  "limit": 10,
  "total": 0,
  "name": "",
  "Members": [
    {
      "ID": "5ec9f5f4-5221-43f4-a56f-9594ab110efa",
      "Type": "users"
    },
    {
      "ID": "8e968002-1b19-4e17-bfb6-f0064888a2d1",
      "Type": "users"
    },
    {
      "ID": "a0b1d516-67c6-4e8d-8ea2-ad4aff444ca3",
      "Type": "things"
    },
    {
      "ID": "9a036414-5d47-4122-9e58-b3b6953a2097",
      "Type": "things"
    }
  ]
}

You can filter by type

curl -sSX GET http://localhost/groups/01F2TTDYGMP6DW083NE6E0DKH2/members\?type\='users'  -H "Authorization: $TOK" | jq
{
  "limit": 10,
  "total": 2,
  "level": 0,
  "name": "",
  "Members": [
    {
      "ID": "5ec9f5f4-5221-43f4-a56f-9594ab110efa",
      "Type": "users"
    },
    {
      "ID": "8e968002-1b19-4e17-bfb6-f0064888a2d1",
      "Type": "users"
    }
  ]
}

Fetching from users service#

curl -sSX GET http://localhost/groups/users/01F2TTDYGMP6DW083NE6E0DKH2  -H "Authorization: $TOK" | jq        
{
  "total": 2,
  "offset": 0,
  "limit": 10,
  "users": [
    {
      "id": "5ec9f5f4-5221-43f4-a56f-9594ab110efa",
      "email": "admin@example.com"
    },
    {
      "id": "8e968002-1b19-4e17-bfb6-f0064888a2d1",
      "email": "moko@example.com"
    }
  ]
}

Fetching from things service#

 curl -sSX GET http://localhost/groups/things/01F2TTDYGMP6DW083NE6E0DKH2  -H "Authorization: $TOK" | jq
{
  "total": 2,
  "offset": 0,
  "limit": 10,
  "order": "",
  "direction": "",
  "things": [
    {
      "id": "a0b1d516-67c6-4e8d-8ea2-ad4aff444ca3",
      "key": "54dfc44c-3471-4903-a6b5-529dc7a2dd41"
    },
    {
      "id": "9a036414-5d47-4122-9e58-b3b6953a2097",
      "key": "e874fc75-461d-4ece-ac55-2d7cdc10c20a"
    }
  ]
}

Fetching membership#

For entity that is being put in multiple groups it is possible to retrieve a list of groups it belongs to.

curl -sSX GET http://localhost/members/<member_id>/groups  -H "Authorization: $TOK" | jq 
{
  "total": 1,
  "level": 0,
  "name": "",
  "groups": [
    {
      "id": "01F2TTDYGMP6DW083NE6E0DKH2",
      "name": "test",
      "owner_id": "8e968002-1b19-4e17-bfb6-f0064888a2d1",
      "description": "group for test",
      "metadata": {
        "group_attr": "attr_value"
      },
      "level": 0,
      "path": "",
      "created_at": "0001-01-01T00:00:00Z",
      "updated_at": "0001-01-01T00:00:00Z"
    }
  ]
}

• member_id - is either thing or user id, or some other enitity if groups are being used for grouping external entities.