User Groups

This technical design describes implementation and API for User Groups.

User Groups API

POST /api/user-groups/

Creates Users Group.

Permissions

Requires authentication and user_groups.create permission.

Request

Headers

Request Method: POST
Content-Type: application/json
Location: /api/user-groups/
Authorization: JWT access_token

Body

Key	Type	Required	Notes
name	string	true
description	string	false

Validations

name
- This field is required.
- This field must be unique.
- This field may not be blank.
- Ensure this field has no more than 80 characters.
description
- Ensure this field has no more than 500 characters.
- This field may not be null

Sample request body

json

{
    "name": "test_group",
    "description": "Sample description"
}

Response

Key	Type	Notes
id	int	Automatically generated by the backend.
name	string
description	string
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
num_of_members	int
num_of_owners	int
_meta.permissions	Object	Object describing permissions.

Successful status 201 Created
Response body schema

json

{
    "id": 1,
    "name": "test_group",
    "description": "Sample description",
    "created_by": {
        "id": 11,
        "first_name": "ALX User Super Admin",
        "last_name": "Full permissions",
        "username": "api.alx.user+super_admin_new@gmail.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "super_admin"
    },
    "modified_by": {
        "id": 11,
        "first_name": "ALX User Super Admin",
        "last_name": "Full permissions",
        "username": "api.alx.user+super_admin_new@gmail.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "super_admin"
    },
    "num_of_members": 0,
    "num_of_owners": 0,
    "created_at": "2022-04-22T09:14:46.990000+02:00",
    "modified_at": "2022-04-22T09:14:46.990000+02:00",
    "_meta": {
        "permissions": {
            "create": true,
            "list": true,
            "view": true,
            "edit": true,
            "delete": true,
            "edit_perm_sets": true,
            "edit_members": true,
            "edit_owners": true
        }
    }
}

Errors

Cause	Response code	Message
"name" is missing	400 Bad Request	"name": ["This field is required."]
"name" is not unique	400 Bad Request	"name": ["This field must be unique."]
"name" is blank	400 Bad Request	"name": ["This field may not be blank."]
"name" is not too long	400 Bad Request	"name": ["Ensure this field has no more than 80 characters."]
"description" is too long	400 Bad Request	"description": ["Ensure this field has no more than 500 characters."]
"description" is null	400 Bad Request	"description": ["This field may not be null."]
limit exceed	400 Bad Request	"detail": "Limit of 1000 Users Groups has been exceeded."
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."

PATCH /api/user-groups/`id`/

Updates single Users Group.

Permissions

Requires authentication and user_groups.edit permission.

Request

Headers

Request Method: PATCH
Content-Type: application/json
Location: /api/user-groups/
Authorization: JWT access_token

Body

Key	Type	Required	Notes
name	string	true
description	string	false

Validations

name
- This field must be unique.
- This field may not be blank.
- Ensure this field has no more than 80 characters.
description
- Ensure this field has no more than 500 characters.
- This field may not be null

Sample request body

json

{
    "name": "test_group",
    "description": "Sample description"
}

Response

Key	Type	Notes
id	int	Automatically generated by the backend.
name	string
description	string
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
num_of_members	int
num_of_owners	int
_meta.permissions	Object	Object describing permissions.

Successful status 200 OK
Response body schema

json

{
    "id": 1,
    "name": "test_group",
    "description": "Sample description",
    "created_by": {
        "id": 11,
        "first_name": "ALX User Super Admin",
        "last_name": "Full permissions",
        "username": "api.alx.user+super_admin_new@gmail.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "super_admin"
    },
    "modified_by": {
        "id": 11,
        "first_name": "ALX User Super Admin",
        "last_name": "Full permissions",
        "username": "api.alx.user+super_admin_new@gmail.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "super_admin"
    },
    "num_of_members": 0,
    "num_of_owners": 0,
    "created_at": "2022-04-22T09:14:46.990000+02:00",
    "modified_at": "2022-04-22T09:14:46.990000+02:00",
    "_meta": {
        "permissions": {
            "create": true,
            "list": true,
            "view": true,
            "edit": true,
            "delete": true,
            "edit_perm_sets": true,
            "edit_members": true,
            "edit_owners": true
        }
    }
}

Errors

Cause	Response code	Message
"name" is not unique	400 Bad Request	"name": ["This field must be unique."]
"name" is blank	400 Bad Request	"name": ["This field may not be blank."]
"name" is not too long	400 Bad Request	"name": ["Ensure this field has no more than 80 characters."]
"description" is too long	400 Bad Request	"description": ["Ensure this field has no more than 500 characters."]
"description" is null	400 Bad Request	"description": ["This field may not be null."]
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."

GET /api/user-groups/

Returns list of Users Groups.

Permissions

Requires authentication and user_groups.list permission.

Request example

Headers

Request Method: GET
Content-Type: application/json
Location: /api/user-groups/
Authorization: JWT access_token

Response

Key	Type	Notes
limit	int
offset	int
total_count	int	Total number of results visible to the user (based on permissions).
filtered_count	int	Number of results visible to the user (based on permissions) with filters applied.
next	url	Next page URL (null if there is no next page)
previous	url	Previous page URL (null if there is no previous page)
results	Array	List of results. Described in the next table.

Response `results` array

Key	Type	Notes
id	int	Automatically generated by the backend.
name	string
description	string
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
num_of_members	int
num_of_owners	int
_meta.permissions	Object	Object describing permissions.

Successful status 200 OK
Response body schema

json

{
    "limit": 50,
    "offset": 0,
    "filtered_count": 2,
    "total_count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "name": "test_user_group",
            "description": "",
            "created_by": {
                "id": 11,
                "first_name": "ALX User Super Admin",
                "last_name": "Full permissions",
                "username": "api.alx.user+super_admin_new@gmail.com",
                "company_name": "",
                "is_deleted": false,
                "account_type": "super_admin"
            },
            "modified_by": {
                "id": 11,
                "first_name": "ALX User Super Admin",
                "last_name": "Full permissions",
                "username": "api.alx.user+super_admin_new@gmail.com",
                "company_name": "",
                "is_deleted": false,
                "account_type": "super_admin"
            },
            "num_of_members": 0,
            "num_of_owners": 0,
            "created_at": "2022-04-22T09:14:46.990000+02:00",
            "modified_at": "2022-04-22T09:14:46.990000+02:00",
            "_meta": {
                "permissions": {
                    "create": true,
                    "list": true,
                    "view": true,
                    "edit": true,
                    "delete": true,
                    "edit_perm_sets": true
                }
            }
        },
        {
            "id": 2,
            "name": "test_user_group1",
            "description": "",
            "created_by": {
                "id": 11,
                "first_name": "ALX User Super Admin",
                "last_name": "Full permissions",
                "username": "api.alx.user+super_admin_new@gmail.com",
                "company_name": "",
                "is_deleted": false,
                "account_type": "super_admin"
            },
            "modified_by": {
                "id": 11,
                "first_name": "ALX User Super Admin",
                "last_name": "Full permissions",
                "username": "api.alx.user+super_admin_new@gmail.com",
                "company_name": "",
                "is_deleted": false,
                "account_type": "super_admin"
            },
            "num_of_members": 0,
            "num_of_owners": 0,
            "created_at": "2022-04-22T09:15:04.586000+02:00",
            "modified_at": "2022-04-22T09:15:04.586000+02:00",
            "_meta": {
                "permissions": {
                    "create": true,
                    "list": true,
                    "view": true,
                    "edit": true,
                    "delete": true,
                    "edit_perm_sets": true,
                    "edit_members": true,
                    "edit_owners": true
                }
            }
        }
    ]
}

Sorting

Parameter	Example	Notes
id	/api/user-groups/?ordering=id	Ascending
id	/api/user-groups/?ordering=-id	Descending (-)
name	/api/user-groups/?ordering=name	Ascending
name	/api/user-groups/?ordering=-name	Descending (-)
created_at	/api/user-groups/?ordering=created_at	Ascending
created_at	/api/user-groups/?ordering=-created_at	Descending (-)
modified_at	/api/user-groups/?ordering=modified_at	Ascending
modified_at	/api/user-groups/?ordering=-modified_at	Descending (-)
num_of_members	/api/user-groups/?ordering=num_of_members	Ascending
num_of_members	/api/user-groups/?ordering=-num_of_members	Descending (-)
num_of_owners	/api/user-groups/?ordering=num_of_owners	Ascending
num_of_owners	/api/user-groups/?ordering=-num_of_owners	Descending (-)

Filtering

Please check ALX API standards for predicates available per type.

Parameter	Type
id	int
name	string
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
num_of_members	int
num_of_owners	int
members	(exact only)

Errors

Error	Response code	Message
Wrong ordering value	400 Bad Request	"ordering": ["Select a valid choice. {value} is not one of the available choices."]

GET api/user-groups/`id`/

Returns single Users Group by id.

Permissions

Requires authentication and user_groups.view permission.

URL parameters

Key	Type	Notes
id	id

Request example

Headers

Request Method: GET
Content-Type: application/json
Location: api/user-groups/1/
Authorization: JWT access_token

Response

Key	Type	Notes
id	int	Automatically generated by the backend.
name	string
description	string
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
num_of_members	int
num_of_owners	int
_meta.permissions	Object	Object describing permissions.

Successful status 200 OK
Response body schema:

json

{
    "id": 1,
    "name": "test_user_group",
    "description": "",
    "created_by": {
        "id": 11,
        "first_name": "ALX User Super Admin",
        "last_name": "Full permissions",
        "username": "api.alx.user+super_admin_new@gmail.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "super_admin"
    },
    "modified_by": {
        "id": 11,
        "first_name": "ALX User Super Admin",
        "last_name": "Full permissions",
        "username": "api.alx.user+super_admin_new@gmail.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "super_admin"
    },
    "num_of_members": 0,
    "num_of_owners": 0,
    "created_at": "2022-04-22T09:14:46.990000+02:00",
    "modified_at": "2022-04-22T09:14:46.990000+02:00",
    "_meta": {
        "permissions": {
            "create": true,
            "list": true,
            "view": true,
            "edit": true,
            "delete": true,
            "edit_perm_sets": true,
            "edit_members": true,
            "edit_owners": true
        }
    }
}

Errors

Error	Response code	Message
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."
Users Group with "id" does not exist	404 Not Found	"detail": "Not found."

DELETE /api/user-groups/`users-group_id`/

Remove a Users Group with checking if no used anywhere.

Permissions

Requires authentication and user_groups.delete permission.

Request example

Headers

Request Method: DELETE
Location: /api/user-groups/1/
Authorization: JWT access_token

Response example

Status 204 No Content
Body

Errors

Error	Response code	Message
Users Group in use - Sequences	400 Forbidden	"detail": "Users Group is in use by Sequences."
Users Group in use - Permission sets	400 Forbidden	"detail": "Users Group is in use by User group permission sets."
Users Group in use - ObjectClassField	400 Forbidden	"detail": "Users Group is in use by Object class fields."
Users Group in use - Object Class Permission sets	400 Forbidden	"detail": "Users Group is in use by Object Class permission sets."
Users Group in use - Task assignment	400 Forbidden	"detail": "Users Group is in use by Task assignment."
Users Group in use - Object Record Permission sets	400 Forbidden	"detail": "Users Group is in use by Object Record permission sets."
Insufficient permissions	403 Forbidden	"detail": "You do not have permission to perform this action."
Users Group does not exist	404 Forbidden	"detail": "Not found"

GET /api/user-groups/`users_group_id`/usage/

Permissions

Requires authentication and user_groups.view permission.

Request example

Headers

Request Method: GET
Location: /api/user-groups/1/usage/
Authorization: JWT access_token

Response

Key	Type	Notes
sequences	array
num_of_sequences	int
user_groups	array
num_of_user_groups	int
object_classes_fields	array
num_of_object_classes_fields	int
object_classes_permission_sets	array
num_of_object_classes_permission_sets	int
object_record_permission_sets	array
num_of_object_record_permission_sets	int
num_of_tasks	int

Response `sequences` array

Key	Type	Notes
id	int	Sequence id
name	str	Name of sequence

Response `user_groups` array

Key	Type	Notes
id	int	Users Group id
name	str	Users Group name
permission_sets	array	Users Group Permission sets array

Response `permission_sets` array

Key	Type	Notes
id	int	Permission set id
name	str	Permission set name

Response `object_classes_fields` array

Key	Type	Notes
id	int	ObjectClassField id
name	str	ObjectClassField name
object_class_id	int	Field Class id
object_class_name	str	Field Class name

Response `object_classes_permission_sets` array

Key	Type	Notes
id	int	Permission set id
name	str	Permission set name
object_class_id	int	Permission set Class id
object_class_name	str	Permission set Class name

Response `object_record_permission_sets` array

Key	Type	Notes
id	int	Permission set id
name	str	Permission set name
object_class_id	int	Permission set Class id
object_class_name	str	Permission set Class name

Response `tasks` array

Key	Type	Notes
id	int	Permission set id
name	str	Permission set name

Response example

Status 200 OK
Body

json

{
    "sequences": [
        {
            "id": 1,
            "name": "sequence1"
        },
        {
            "id": 7,
            "name": "sequence_test"
        }
    ],
    "num_of_sequences": 2,
    "user_groups": [
        {
            "id": 12,
            "name": "Group12",
            "permission_sets": [
                {
                    "id": 3,
                    "name": "Custom1"
                }
            ]
        }
    ],
    "num_of_user_groups": 1,
    "object_classes_fields": [
        {
            "id": 1,
            "name": "Name1",
            "object_class_id": 2,
            "object_class_name": "Class2"
        },
        {
            "id": 2,
            "name": "Name2",
            "object_class_id": 1,
            "object_class_name": "Class1"
        }
    ],
    "num_of_object_classes_fields": 2,
    "object_classes_permission_sets": [
        {
            "id": 1,
            "name": "PermSet1",
            "object_class_id": 2,
            "object_class_name": "Class2"
        }
    ],
    "num_of_object_classes_permission_sets": 1,
    "object_record_permission_sets": [
        {
            "id": 1,
            "name": "PermSet1",
            "object_class_id": 2,
            "object_class_name": "Class2"
        }
    ],
    "num_of_object_record_permission_sets": 1,
    "num_of_tasks": 1
}

Errors

Error	Response code	Message
User Group in use	400 Forbidden	"detail": "Users Group is in use by Sequences."
`id` is invalid	404 Bad Request	'detail': "Not found."
Unauthorized API call	403 Bad Request	'detail': "You do not have permission to perform this action."

OPTIONS /api/user-groups/

Permissions

Requires authentication only.

Request

Headers

Request Method: OPTIONS
Content-Type: application/json
Location: /api/user-groups/
Authorization: JWT access_token

Response

Successful status 200 OK
Response body:

json

{
    "list": {
        "columns": [
            {
                "alias": "id",
                "type": "int",
                "predicates": [
                    "exact",
                    "gt",
                    "gte",
                    "lt",
                    "lte",
                    "range"
                ],
                "sort_ok": true
            },
            {
                "alias": "name",
                "type": "string",
                "predicates": [
                    "exact",
                    "iexact",
                    "contains",
                    "icontains",
                    "startswith",
                    "istartswith",
                    "endswith",
                    "iendswith"
                ],
                "sort_ok": true
            },
            {
                "alias": "description",
                "type": "string",
                "predicates": [],
                "sort_ok": false
            },
            {
                "alias": "created_by",
                "type": "user",
                "predicates": [
                    "exact",
                    "in"
                ],
                "sort_ok": false,
                "autocomplete": "/api/users/autocomplete/?text__icontains="
            },
            {
                "alias": "modified_by",
                "type": "user",
                "predicates": [
                    "exact",
                    "in"
                ],
                "sort_ok": false,
                "autocomplete": "/api/users/autocomplete/?text__icontains="
            },
            {
                "alias": "num_of_members",
                "type": "int",
                "predicates": [
                    "exact",
                    "gt",
                    "gte",
                    "lt",
                    "lte",
                    "range"
                ],
                "sort_ok": true
            },
            {
                "alias": "num_of_owners",
                "type": "int",
                "predicates": [
                    "exact",
                    "gt",
                    "gte",
                    "lt",
                    "lte",
                    "range"
                ],
                "sort_ok": true
            },
            {
                "alias": "created_at",
                "type": "datetime",
                "predicates": [
                    "exact",
                    "gt",
                    "gte",
                    "lt",
                    "lte",
                    "range"
                ],
                "sort_ok": true
            },
            {
                "alias": "modified_at",
                "type": "datetime",
                "predicates": [
                    "exact",
                    "gt",
                    "gte",
                    "lt",
                    "lte",
                    "range"
                ],
                "sort_ok": true
            }
        ]
    },
    "details": {
        "schema": [
            {
                "alias": "name",
                "type": "string",
                "required": true,
                "validators": [
                    {
                        "type": "max_length",
                        "length": 80
                    }
                ]
            },
            {
                "alias": "description",
                "type": "string",
                "required": false,
                "validators": [
                    {
                        "type": "max_length",
                        "length": 500
                    }
                ]
            }
        ]
    },
    "restrictions": {
        "limit_items": 1000
    }
}

GET /api/user-groups/autocomplete/

List of User Groups sorted by name ascending by default, based on query parameters for autocomplete widgets.

Permissions

Requires authentication only.

Request example

Headers

Request Method: GET
Location: /api/user-groups/autocomplete/
Authorization: JWT access_token

Response

Key	Type	Notes
limit	int
offset	int
total_count	int	Total number of forms visible to the user (based on permissions).
filtered_count	int	Number of forms visible to the user (based on permissions) with filters applied.
next	URL / null	Next page URL (null if there is no next page)
previous	URL / null	Previous page URL (null if there is no previous page)
results	Array	Described in the next table.

Response `results` array

Key	Type	Notes
value	int	User Group ID
text	str	User Group name
num_of_members	int

Response example

Status 200 OK
Body

json

{
  "limit": 100,
  "offset": 0,
  "filtered_count": 1,
  "total_count": 20,
  "next": null,
  "previous": null,
  "results": [
    {
      "value": 12,
      "text": "Some group name",
      "num_of_members": 2
    }
  ]
}

Sorting

Parameter	Example	Notes
text	{build}/api/user-groups/autocomplete/?ordering=text	Ascending
text	{build}/api/user-groups/autocomplete/?ordering=-text	Descending (-)

Filtering

For the full description of standard predicates see ALX API standards - Developers guide.

Parameter	Predicates	Example	Values
text	icontains	{build}/api/user-groups/autocomplete/?text__icontains=template

Errors

Error	Response code	Message
Wrong ordering value	400 Bad Request	"ordering": ["Select a valid choice. {value} is not one of the available choices."]

GET /api/user-groups/autocomplete/users-combined/

Deprecated

⚠️ This endpoint is no longer supported starting from version 11.0.0.

Returns combined list of users and users groups.

Permissions

Requires authentication and superadmin or standard_user account type.

Request example

Headers

Request Method: GET
Location: /api/user-groups/autocomplete/users-combined/
Authorization: JWT access_token

Response

Key	Type	Notes
limit	int
offset	int
total_count	int	Total number of items visible to the user (based on permissions).
filtered_count	int	Number of items visible to the user (based on permissions) with filters applied.
next	URL / null	Next page URL (null if there is no next page)
previous	URL / null	Previous page URL (null if there is no previous page)
results	Array	Described in the next table.

Response `results` array

Users Group result schema

Key	Type	Notes
id	id
resource	string
value	int
text	string

User result schema

Key	Type	Notes
id	id
resource	string
value	int
text	string
first_name	string
last_name	string
company_name	string
account_type	string

Response example

Status 200 OK
Body

json

{
  "limit": 100,
  "offset": 0,
  "filtered_count": 2,
  "total_count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "resource": "users",
      "value": 345,
      "text": "John Smith (j.smith@alx.test)",
      "username": "j.smith@alx.test",
      "first_name": "John",
      "last_name": "Smith",
      "company_name": "Autologyx",
      "account_type": "full"
    },
    {
      "id": 2,
      "resource": "user_groups",
      "value": 345,
      "text": "Smith group"
    }
  ]
}

Sorting

Parameter	Example	Notes
text	{build}/api/user-groups/autocomplete/users-combined/?ordering=text	Ascending
text	{build}/api/user-groups/autocomplete/users-combined/?ordering=-text	Descending (-)

Filtering

For the full description of standard predicates see ALX API standards - Developers guide.

Parameter	Type	Notes
id	int
text	string
account_type		Only exact

Important

Specifying by what fields users should be filtered: Filtering users should be specified by users_search_in parameter. It can be applied multiple times. Each usage of the parameter receives single or multiple comma separated possible values:

first_name
last_name
username
company_name

If single usage of the parameter has multi comma separated fields, then they are concatenated by whitespace in the backend. Each usage of users_search_in parameter is joined by OR operator.

Sample: {build}/api/user-groups/autocomplete/users-combined/?users_search_in=first_name,last_name&users_search_in=username&text__icontains=smith

Means: Return users if "smith" (case insensitive) matches to their: • first_name + " " + last_name (for example "John Smith") • OR username (for example "j.smith@alx.test") users_search_in parameter is optional. If the parameter is not passed, then users are search by text.

Errors

Error	Response code	Message
Invalid choice	400 Bad request
Wrong field name	400 Bad request
Requesting user is not authenticated	401 Unauthorized	"detail": "Authentication credentials were not provided."
Unauthorized API call	403 Forbidden	"detail": "You do not have permission to perform this action."

OPTIONS /api/user-groups/`id`/users/

Permissions

Any user.

Request

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

OPTIONS /api/user-groups/1/users/

Response

Successful status 200 OK
Response body:

json

{
    "list": {
        "columns": [
            {
                "alias": "id",
                "type": "int",
                "predicates": [
                    "exact",
                    "gt",
                    "gte",
                    "lt",
                    "lte",
                    "range"
                ],
                "sort_ok": true
            },
            {
                "alias": "username",
                "type": "string",
                "predicates": [
                    "exact",
                    "iexact",
                    "contains",
                    "icontains",
                    "startswith",
                    "istartswith",
                    "endswith",
                    "iendswith"
                ],
                "sort_ok": true
            },
            {
                "alias": "added_at",
                "type": "datetime",
                "predicates": [
                    "exact",
                    "gt",
                    "gte",
                    "lt",
                    "lte",
                    "range"
                ],
                "sort_ok": true
            },
            {
                "alias": "first_name",
                "type": "string",
                "predicates": [],
                "sort_ok": true
            },
            {
                "alias": "last_name",
                "type": "string",
                "predicates": [],
                "sort_ok": true
            },
            {
                "alias": "membership",
                "type": "enum",
                "predicates": [
                    "exact",
                    "in"
                ],
                "sort_ok": false,
                "values": [
                    {
                        "value": "member",
                        "text": "Member"
                    },
                    {
                        "value": "non_member",
                        "text": "Non-member"
                    },
                    {
                        "value": "owner",
                        "text": "Owner"
                    }
                ]
            }
        ]
    },
    "search": "/api/user-groups/1/users/?search=" 
}

GET /api/user-groups/`id`/users/

Permissions

Requires authentication and user_groups.view

Request

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

GET /api/user-groups/1/users/

Response

The response contains only users for which request user has users.list permission.

Key	Type	Notes
limit	int
offset	int
total_count	int	Total number of items visible to the user (based on permissions).
filtered_count	int	Number of items visible to the user (based on permissions) with filters applied.
next	URL / null	Next page URL (null if there is no next page)
previous	URL / null	Previous page URL (null if there is no previous page)
results	Array	Described in the next table.

Response `results` array

Key	Type	Notes
id	id
username	string
first_name	string
last_name	string
company_name	string
membership	string
added_at	datetime

Successful status 200 OK
Response body schema

json

{
    "limit": 50,
    "offset": 0,
    "filtered_count": 2,
    "total_count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 2,
            "username": "alx.dev@autologyx.com",
            "added_at": null,
            "first_name": "ALX",
            "last_name": "Developer",
            "company_name": "",
            "membership": "non_member"
        },
        {
            "id": 3,
            "username": "a20211105131728283@yopmail.com",
            "added_at": null,
            "first_name": "Alicja",
            "last_name": "Brzęczyszczykiewicz",
            "company_name": "",
            "membership": "non_member"
        }
    ]
}

Sorting

Parameter	Example	Notes
id	{build}/api/user-groups/{id}/users/?ordering=id	Ascending
id	{build}/api/user-groups/{id}/users/?ordering=-id	Descending (-)
username	{build}/api/user-groups/{id}/users/?ordering=username	Ascending
username	{build}/api/user-groups/{id}/users/?ordering=-username	Descending (-)
added_at	{build}/api/user-groups/{id}/users/?ordering=added_at	Ascending
added_at	{build}/api/user-groups/{id}/users/?ordering=-added_at	Descending (-)
first_name	{build}/api/user-groups/{id}/users/?ordering=first_name	Ascending
first_name	{build}/api/user-groups/{id}/users/?ordering=-first_name	Descending (-)
last_name	{build}/api/user-groups/{id}/users/?ordering=last_name	Ascending
last_name	{build}/api/user-groups/{id}/users/?ordering=-last_name	Descending (-)

Filtering

For the full description of standard predicates see ALX API standards - Developers guide.

Parameter	Type
id	int
username	string
membership	enum
added_at	datetime

Search

Search Functionality based on DRF SearchFilter

The search is case-insensitive. This API endpoint supports searching for users based on the following fields: first_name, last_name, and username. The search functionality allows for partial matches and can handle quoted phrases as single search terms. If multiple search terms are used, then objects will be returned to the list only if all the provided terms are matched. Search Fields

first_name
last_name
username

Main

Usage

To perform a search, include the search query parameter in your request. The search will be executed against the specified fields. Examples

Search by single term:

GET /api/user-groups/1/users/?search=John

This will return users whose first_name, last_name, or username contains john.

Search by multiple terms:

GET /api/user-groups/1/users/?search=john smith

This will return users whose first_name, last_name, or username contains both john and smith.

Search by quoted phrase:

GET /api/user-groups/1/users/?search="john smith"

This will return users whose first_name, last_name, or username contains the exact phrase "john smith".

Errors

Error	Response code	Message
Invalid choice	400 Bad request
Requesting user is not authenticated	401 Unauthorized	"detail": "Authentication credentials were not provided."
Unauthorized API call	403 Forbidden	"detail": "You do not have permission to perform this action."

POST /api/user-groups/`id`/members/

Batch operation - adds single or multiple users (members) to given group. Duplicates are silently ignored.

UsersGroup.num_of_members will be updated. UsersGroup fields modified_at and modified_by will be updated. UsersGroupMembers.created_at and created_by fields will be set if relation does not exist.

Permissions

Requires authentication and user_groups.edit_members

Request

Headers

Request Method: POST
Content-Type: application/json
Location: /api/user-groups/`id`/members/
Authorization: JWT access_token

Schema

POST /api/user-groups/1/members/

Body

list of user ids

json

[
  1, 
  2, 
  3
]

Validations

1 Time Completion accounts cannot be members.
body must be a list of user ids.
user id must be an integer.
user id must exist in the system.
up to 50 users can be added at once.
limit of 1000000 User Group Members cannot be exceeded.

Sample request body

json

[
  1, 
  2, 
  3
]

Response

Key	Type	Notes
id	int	Automatically generated by the backend.
name	string
description	string
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
num_of_members	int
num_of_owners	int
_meta.permissions	Object	Object describing permissions.

Successful status 200 OK
Response body schema:

json

{
    "id": 1,
    "name": "test_user_group",
    "description": "",
    "created_by": {
        "id": 11,
        "first_name": "ALX User Super Admin",
        "last_name": "Full permissions",
        "username": "api.alx.user+super_admin_new@gmail.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "super_admin"
    },
    "modified_by": {
        "id": 11,
        "first_name": "ALX User Super Admin",
        "last_name": "Full permissions",
        "username": "api.alx.user+super_admin_new@gmail.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "super_admin"
    },
    "num_of_members": 3,
    "num_of_owners": 0,
    "created_at": "2022-04-22T09:14:46.990000+02:00",
    "modified_at": "2022-04-22T09:14:46.990000+02:00",
    "_meta": {
        "permissions": {
            "create": true,
            "list": true,
            "view": true,
            "edit": true,
            "delete": true,
            "edit_perm_sets": true,
            "edit_members": true,
            "edit_owners": true
        }
    }
}

Errors

Cause	Response code	Message
empty list	400 Bad Request	"detail": ["This list may not be empty."]
max batch limit exceeded	400 Bad Request	"detail": ["Up to 50 items allowed."]
null/empty list sent instead of list of ids	400 Bad Request	"detail": ["This list may not be empty"]
Insufficient permissions to user	400 Bad Request	"detail": ["You do not have permission to add user "user_id" to User Group "group_id"."]
wrong type send instead of list of ids	400 Bad Request	"detail": ["Expected a list of items but got type "type"."]
wrong type in a list	400 Bad Request	"detail": ["Incorrect type. Expected pk value, received "type"."]
not existed user on list	400 Bad Request	"detail": ["Invalid pk "pk" - object does not exist."]
1 Time Completion accounts cannot be members	400 Bad Request	"detail": ["1 Time Completion account "user_1tc_id" cannot be member."]
limit exceed	400 Bad Request	"detail": ["Limit of 1000000 User Group Members has been exceeded."]
Requesting user is not authenticated	401 Unauthorized	"detail": "Authentication credentials were not provided."
Insufficient permissions	403 Forbidden	"detail": ["You do not have permission to perform this action."]

OPTIONS /api/user-groups/`id`/members/

Permissions

Requires authentication

Request

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

OPTIONS /api/user-groups/1/members/

Response

Successful status 200 OK
Response body:

json

{ 
    "batch": { 
        "type": "set", 
        "required": true, 
        "autocomplete": "/api/users/autocomplete/?account_type!=one_time_completion&text__icontains=" 
    }, 
    "restrictions": { 
        "limit_items": 1000000, 
        "limit_items_in_batch": 50 
    } 
}

DELETE /api/user-groups/`user_group_id`/members/

Batch operation - removes users (members) from a given group. Duplicates are silently ignored.

UsersGroup.num_of_members will be updated. UsersGroup fields modified_at and modified_by will be updated.

Permissions

Requires authentication and user_groups.edit_members permission.

Request

URL parameters

Key	Notes
user_group_id	User Group ID

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

DELETE /api/user-groups/1/members/

Body

list of user ids

json

[
  1, 
  2, 
  3
]

Response

Key	Type	Notes
id	int	Automatically generated by the backend.
name	string
description	string
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
num_of_members	int
num_of_owners	int
_meta.permissions	Object	Object describing permissions.

Successful status 200 OK
Response body schema:

json

{
    "id": 1,
    "name": "test_user_group",
    "description": "",
    "created_by": {
        "id": 11,
        "first_name": "ALX User Super Admin",
        "last_name": "Full permissions",
        "username": "api.alx.user+super_admin_new@gmail.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "super_admin"
    },
    "modified_by": {
        "id": 11,
        "first_name": "ALX User Super Admin",
        "last_name": "Full permissions",
        "username": "api.alx.user+super_admin_new@gmail.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "super_admin"
    },
    "num_of_members": 0,
    "num_of_owners": 0,
    "created_at": "2022-04-22T09:14:46.990000+02:00",
    "modified_at": "2022-04-22T09:14:46.990000+02:00",
    "_meta": {
        "permissions": {
            "create": true,
            "list": true,
            "view": true,
            "edit": true,
            "delete": true,
            "edit_perm_sets": true,
            "edit_members": true,
            "edit_owners": true
        }
    }
}

Errors

Cause	Response code	Message
empty list	400 Bad Request	"detail": ["This list may not be empty."]
max batch limit exceeded	400 Bad Request	"detail": ["Up to 50 items allowed."]
null/empty list sent instead of list of ids	400 Bad Request	"detail": ["This list may not be empty"]
wrong type send instead of list of ids	400 Bad Request	"detail": ["Expected a list of items but got type "type"."]
wrong type on a list	400 Bad Request	"detail": ["Incorrect type. Expected pk value, received "type"."]
not existed user on list	400 Bad Request	"detail": ["Invalid pk "pk" - object does not exist."]
Requesting user is not authenticated	401 Unauthorized	"detail": "Authentication credentials were not provided."
Insufficient permissions	403 Forbidden	"detail": ["You do not have permission to perform this action."]

GET /api/user-groups/`user_group_id`/members/

Returns list of Users Group members.

Permissions

Requires authentication and user_groups.view permission.

Request example

Headers

Request Method: GET
Content-Type: application/json
Location: /api/user-groups/1/members/
Authorization: JWT access_token

Response

Key	Type	Notes
limit	int
offset	int
total_count	int	Total number of results visible to the user (based on permissions).
filtered_count	int	Number of results visible to the user (based on permissions) with filters applied.
next	url	Next page URL (null if there is no next page)
previous	url	Previous page URL (null if there is no previous page)
results	Array	List of results. Described in the next table.

Response `results` array

Key	Type	Notes
id	int	User id
username	string
added_at	string
first_name	string
last_name	string
company_name	string
membership	string

Successful status 200 OK
Response body schema

json

{
    "limit": 50,
    "offset": 0,
    "filtered_count": 1,
    "total_count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "username": "Name",
            "added_at": "2022-04-22T09:14:46.990000+02:00",
            "first_name": "First",
            "last_name": "Last",
            "company_name": "",
            "membership": "member"
        }
    ]
}

Sorting

Parameter	Example	Notes
id	/api/user-groups/1/members/?ordering=id	Ascending
id	/api/user-groups/1/members/?ordering=-id	Descending (-)
username	/api/user-groups/1/members/?ordering=username	Ascending
username	/api/user-groups/1/members/?ordering=-username	Descending (-)
added_at	/api/user-groups/1/members/?ordering=added_at	Ascending
added_at	/api/user-groups/1/members/?ordering=-added_at	Descending (-)

Filtering

Please check ALX API standards for predicates available per type.

Parameter	Type
id	int
username	string
membership	(exact only)

Errors

Error	Response code	Message
Wrong ordering value	400 Bad Request	"membership": ["Select a valid choice. {value} is not one of the available choices."]
Insufficient permissions	403 Forbidden	"detail": ["You do not have permission to perform this action."]
Users Group with "id" does not exist	404 Not Found	"detail": "Not found."

DELETE /api/user-groups/`user_group_id`/members/all/

Clears all users (members) from given users group, so after successful operation there isn’t any member assigned.

UsersGroup.num_of_members will be updated. UsersGroup fields modified_at and modified_by will be updated.

Permissions

Requires authentication and user_groups.edit_members permission.

Request

URL parameters

Key	Notes
user_group_id	User Group ID

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

DELETE /api/user-groups/1/members/all/

Response

Key	Type	Notes
id	int	Automatically generated by the backend.
name	string
description	string
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
num_of_members	int
num_of_owners	int
_meta.permissions	Object	Object describing permissions.

Successful status 200 OK
Response body schema:

json

{
    "id": 1,
    "name": "test_user_group",
    "description": "",
    "created_by": {
        "id": 11,
        "first_name": "ALX User Super Admin",
        "last_name": "Full permissions",
        "username": "api.alx.user+super_admin_new@gmail.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "super_admin"
    },
    "modified_by": {
        "id": 11,
        "first_name": "ALX User Super Admin",
        "last_name": "Full permissions",
        "username": "api.alx.user+super_admin_new@gmail.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "super_admin"
    },
    "num_of_members": 0,
    "num_of_owners": 0,
    "created_at": "2022-04-22T09:14:46.990000+02:00",
    "modified_at": "2022-04-22T09:14:46.990000+02:00",
    "_meta": {
        "permissions": {
            "create": true,
            "list": true,
            "view": true,
            "edit": true,
            "delete": true,
            "edit_perm_sets": true,
            "edit_members": true,
            "edit_owners": true
        }
    }
}

Errors

Cause	Response code	Message
Requesting user is not authenticated	401 Unauthorized	"detail": "Authentication credentials were not provided."
Insufficient permissions	403 Forbidden	"detail": ["You do not have permission to perform this action."]

POST /api/user-groups/`id`/owners/

Batch operation - adds single or multiple users (owners) to a given group. Duplicates are silently ignored.

UsersGroup.num_of_members will be updated. UsersGroup.num_of_owners will be updated. UsersGroup fields modified_at and modified_by will be updated.

Permissions

Requires authentication and user_groups.edit_owners

Request

Headers

Request Method: POST
Content-Type: application/json
Location: /api/user-groups/`id`/owners/
Authorization: JWT access_token

Schema

POST /api/user-groups/1/owners/

Body

list of user ids

json

[
  1, 
  2, 
  3
]

Validations

1 Time Completion accounts cannot be owners.
body must be a list of user ids.
user id must be an integer.
user id must exist in the system.
up to 50 users can be added at once.
limit of 1000000 User Group Members cannot be exceeded.

Sample request body

json

[
  1, 
  2, 
  3
]

Response

Key	Type	Notes
id	int	Automatically generated by the backend.
name	string
description	string
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
num_of_members	int
num_of_owners	int
_meta.permissions	Object	Object describing permissions.

Successful status 200 OK
Response body schema:

json

{
    "id": 1,
    "name": "test_user_group",
    "description": "",
    "created_by": {
        "id": 11,
        "first_name": "ALX User Super Admin",
        "last_name": "Full permissions",
        "username": "api.alx.user+super_admin_new@gmail.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "super_admin"
    },
    "modified_by": {
        "id": 11,
        "first_name": "ALX User Super Admin",
        "last_name": "Full permissions",
        "username": "api.alx.user+super_admin_new@gmail.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "super_admin"
    },
    "num_of_members": 0,
    "num_of_owners": 3,
    "created_at": "2022-04-22T09:14:46.990000+02:00",
    "modified_at": "2022-04-22T09:14:46.990000+02:00",
    "_meta": {
        "permissions": {
            "create": true,
            "list": true,
            "view": true,
            "edit": true,
            "delete": true,
            "edit_perm_sets": true,
            "edit_members": true,
            "edit_owners": true
        }
    }
}

Errors

Cause	Response code	Message
empty list	400 Bad Request	"detail": ["This list may not be empty."]
max batch limit exceeded	400 Bad Request	"detail": ["Up to 50 items allowed."]
null/empty list sent instead of list of ids	400 Bad Request	"detail": ["This list may not be empty"]
Insufficient permissions to user	400 Bad Request	"detail": ["You do not have permission to add user "user_id" as an owner of User Group "group_id"."]
wrong type send instead of list of ids	400 Bad Request	"detail": ["Expected a list of items but got type "type"."]
wrong type in a list	400 Bad Request	"detail": ["Incorrect type. Expected pk value, received "type"."]
not existed user on list	400 Bad Request	"detail": ["Invalid pk "pk" - object does not exist."]
1 Time Completion accounts cannot be owner	400 Bad Request	"detail": ["1 Time Completion account "user_1tc_id" cannot be owner."]
limit exceed	400 Bad Request	"detail": ["Limit of 1000000 User Group Members has been exceeded."]
Requesting user is not authenticated	401 Unauthorized	"detail": "Authentication credentials were not provided."
Insufficient permissions	403 Forbidden	"detail": ["You do not have permission to perform this action."]

OPTIONS /api/user-groups/`id`/owners/

Permissions

Requires authentication

Request

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

OPTIONS /api/user-groups/1/members/

Response

Successful status 200 OK
Response body:

json

{ 
    "batch": { 
        "type": "set", 
        "required": true, 
        "autocomplete": "/api/users/autocomplete/?account_type!=one_time_completion&text__icontains=" 
    }, 
    "restrictions": { 
        "limit_items": 10, 
        "limit_items_in_batch": 10 
    } 
}

DELETE /api/user-groups/`id`/owners/

Batch operation - removes users (owners) from a given group. Duplicates are silently ignored.

UsersGroup.num_of_members will be updated. UsersGroup.num_of_owners will be updated. UsersGroup fields modified_at and modified_by will be updated.

Permissions

Requires authentication and user_groups.edit_owners permission.

Request

URL parameters

Key	Notes
id	User Group ID

Headers

Content-Type: application/json
Authorization: JWT access_token

Schema

DELETE /api/user-groups/1/owners/

Body

list of user ids

json

[
  1, 
  2, 
  3
]

Response

Key	Type	Notes
id	int	Automatically generated by the backend.
name	string
description	string
created_at	datetime
created_by	user
modified_at	datetime
modified_by	user
num_of_members	int
num_of_owners	int
_meta.permissions	Object	Object describing permissions.

Successful status 200 OK
Response body schema:

json

{
    "id": 1,
    "name": "test_user_group",
    "description": "",
    "created_by": {
        "id": 11,
        "first_name": "ALX User Super Admin",
        "last_name": "Full permissions",
        "username": "api.alx.user+super_admin_new@gmail.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "super_admin"
    },
    "modified_by": {
        "id": 11,
        "first_name": "ALX User Super Admin",
        "last_name": "Full permissions",
        "username": "api.alx.user+super_admin_new@gmail.com",
        "company_name": "",
        "is_deleted": false,
        "account_type": "super_admin"
    },
    "num_of_members": 0,
    "num_of_owners": 0,
    "created_at": "2022-04-22T09:14:46.990000+02:00",
    "modified_at": "2022-04-22T09:14:46.990000+02:00",
    "_meta": {
        "permissions": {
            "create": true,
            "list": true,
            "view": true,
            "edit": true,
            "delete": true,
            "edit_perm_sets": true,
            "edit_members": true,
            "edit_owners": true
        }
    }
}

Errors

Cause	Response code	Message
empty list	400 Bad Request	"detail": ["This list may not be empty."]
max batch limit exceeded	400 Bad Request	"detail": ["Up to 10 items allowed."]
null/empty list sent instead of list of ids	400 Bad Request	"detail": ["This list may not be empty"]
wrong type send instead of list of ids	400 Bad Request	"detail": ["Expected a list of items but got type "type"."]
wrong type on a list	400 Bad Request	"detail": ["Incorrect type. Expected pk value, received "type"."]
not existed user on list	400 Bad Request	"detail": ["Invalid pk "pk" - object does not exist."]
Requesting user is not authenticated	401 Unauthorized	"detail": ["Authentication credentials were not provided."]
Insufficient permissions	403 Forbidden	"detail": ["You do not have permission to perform this action."]

GET /api/user-groups/`id`/owners/

Response

Status 405 Method Not Allowed

User Groups ​

User Groups API ​

POST /api/user-groups/ ​

Permissions ​

Request ​

Validations ​

Sample request body ​

Response ​

Errors ​

PATCH /api/user-groups/id/ ​

Permissions ​

Request ​

Validations ​

Sample request body ​

Response ​

Errors ​

GET /api/user-groups/ ​

Permissions ​

Request example ​

Response ​

Response results array ​

Sorting ​

Filtering ​

Errors ​

GET api/user-groups/id/ ​

Permissions ​

URL parameters ​

Request example ​

Response ​

Errors ​

DELETE /api/user-groups/users-group_id/ ​

Permissions ​

Request example ​

Response example ​

Errors ​

GET /api/user-groups/users_group_id/usage/ ​

Permissions ​

Request example ​

Response ​

Response sequences array ​

Response user_groups array ​

Response permission_sets array ​

Response object_classes_fields array ​

Response object_classes_permission_sets array ​

Response object_record_permission_sets array ​

Response tasks array ​

Response example ​

Errors ​

OPTIONS /api/user-groups/ ​

Permissions ​

Request ​

Response ​

GET /api/user-groups/autocomplete/ ​

Permissions ​

Request example ​

Response ​

Response results array ​

Response example ​

Sorting ​

Filtering ​

Errors ​

GET /api/user-groups/autocomplete/users-combined/ ​

Permissions ​

Request example ​

Response ​

Response results array ​

Response example ​

Sorting ​

Filtering ​

Errors ​

OPTIONS /api/user-groups/id/users/ ​

Permissions ​

Request ​

Response ​

GET /api/user-groups/id/users/ ​

Permissions ​

Request ​

Response ​

Response results array ​

Sorting ​

User Groups

User Groups API

POST /api/user-groups/

Permissions

Request

Validations

Sample request body

Response

Errors

PATCH /api/user-groups/`id`/

Permissions

Request

Validations

Sample request body

Response

Errors

GET /api/user-groups/

Permissions

Request example

Response

Response `results` array

Sorting

Filtering

Errors

GET api/user-groups/`id`/

Permissions

URL parameters

Request example

Response

Errors

DELETE /api/user-groups/`users-group_id`/

Permissions

Request example

Response example

Errors

GET /api/user-groups/`users_group_id`/usage/

Permissions

Request example

Response

Response `sequences` array

Response `user_groups` array

Response `permission_sets` array

Response `object_classes_fields` array

Response `object_classes_permission_sets` array

Response `object_record_permission_sets` array

Response `tasks` array

Response example

Errors

OPTIONS /api/user-groups/

Permissions

Request

Response

GET /api/user-groups/autocomplete/

Permissions

Request example

Response

Response `results` array

Response example

Sorting

Filtering

Errors

GET /api/user-groups/autocomplete/users-combined/

Permissions

Request example

Response

Response `results` array

Response example

Sorting

Filtering

Errors

OPTIONS /api/user-groups/`id`/users/

Permissions

Request

Response

GET /api/user-groups/`id`/users/

Permissions

Request

Response

Response `results` array

Sorting