Domains

Domains are a way to organize and manage your application’s data and business logic. They represent specific areas of functionality and help to separate concerns, making assignments to entities more straightforward.

Domains can encapsulate related data and behavior, making it easier to manage complexity and enforce business rules. For example, multiple entities would be accessible through a single domain, which only users with certain permissions can access.

Interaction with other application components

Domains interact with various components of the application, including:

Data filtering and segmentation

Domains can help to filter and segment data based on specific criteria, making it easier to manage and analyze and work with data services. When querying data, domains can be used to specify which entities and relationships should be included in the results, ensuring that only relevant information is returned.

User and role scoping

Domains can also be used to enforce user and role-based access control, ensuring that only authorized users can access specific data and functionality. For example, a user with a specific role may only be able to access data within a certain domain, while another user with a different role may have access to multiple domains. Also, a user assigned to a specific domain may only be able to view and interact with entities and relationships within that domain, if it belongs to their permissions.

Menu visibility within domains

Some menu items and actions may be restricted based on the user’s domain assignments and permissions. Some category menu and menu items might only be accessible if the user has access to the corresponding domain, assigned from another user with the appropriate permissions.

Endpoints for domain management

Below are the available endpoints for managing domains:

Get all domains

Retrieve all domains.

Endpoint:

GET /api/v1/domains

Parameters:

Name	Type	From	Description
active	boolean	query	Filter by active status (true, false, empty)
name	string	query	Filter by domain name (partial match)

Example response:

{
    "error": false,
    "status": 200,
    "message": "string",
    "errors": [
        {}
    ],
    "data": [
        {
            "id": 0,
            "name": "Any domain",
            "description": "Any description",
            "subDomains": [
                "string"
            ],
            "parentId": 0,
            "createdAt": "1970-01-01T00:00:00Z",
            "updatedAt": "1970-01-01T00:00:00Z",
            "active": true
        }
    ],
    "pagination": {
        "hasPreviousPage": true,
        "hasNextPage": true,
        "previousPage": 0,
        "nextPage": 0,
        "recordsTotal": 0,
        "currentPage": 0,
        "startIndex": 0,
        "numPages": 0,
        "limit": 0
    }
}

Fetch a specific domain

Retrieve data for a specific domain by its ID.

Endpoint:

GET /api/v1/domains/:domainId

Parameters:

Name	Type	From	Description
domainId	number	path	The ID of the domain

Example response:

{
    "error": false,
    "status": 200,
    "message": "string",
    "errors": [
        {}
    ],
    "data": {
        "id": 0,
        "name": "Any domain",
        "description": "Any description",
        "subDomains": [
            "string"
        ],
        "parentId": 0,
        "createdAt": "1970-01-01T00:00:00Z",
        "updatedAt": "1970-01-01T00:00:00Z",
        "active": true
    },
    "pagination": {
        "hasPreviousPage": true,
        "hasNextPage": true,
        "previousPage": 0,
        "nextPage": 0,
        "recordsTotal": 0,
        "currentPage": 0,
        "startIndex": 0,
        "numPages": 0,
        "limit": 0
    }
}

Add a new domain

Add a new domain.

Endpoint:

PUT /api/v1/domains

Request body:

{
    "domain": {
        "name": "Any domain",
        "description": "Any description",
        "parentId": 0,
        "active": true
    }
}

Example response:

{
    "error": false,
    "status": 200,
    "message": "string",
    "errors": [
        {}
    ],
    "data": {
        "id": 0,
        "name": "Any domain",
        "description": "Any description",
        "subDomains": [
            "string"
        ],
        "parentId": 0,
        "createdAt": "1970-01-01T00:00:00Z",
        "updatedAt": "1970-01-01T00:00:00Z",
        "active": true
    },
    "pagination": {
        "hasPreviousPage": true,
        "hasNextPage": true,
        "previousPage": 0,
        "nextPage": 0,
        "recordsTotal": 0,
        "currentPage": 0,
        "startIndex": 0,
        "numPages": 0,
        "limit": 0
    }
}

Update domain fields

Update fields of an existing domain.

Endpoint:

PATCH /api/v1/domains/:domainId

Parameters:

Name	Type	From	Description
domainId	number	path	The ID of the domain

Request body:

{
    "name": "Any domain",
    "description": "Any description",
    "parentId": 0,
    "active": true
}

Example response:

{
    "error": false,
    "status": 200,
    "message": "string",
    "errors": [
        {}
    ],
    "data": {
        "id": 0,
        "name": "Any domain",
        "description": "Any description",
        "subDomains": [
            "string"
        ],
        "parentId": 0,
        "createdAt": "1970-01-01T00:00:00Z",
        "updatedAt": "1970-01-01T00:00:00Z",
        "active": true
    },
    "pagination": {
        "hasPreviousPage": true,
        "hasNextPage": true,
        "previousPage": 0,
        "nextPage": 0,
        "recordsTotal": 0,
        "currentPage": 0,
        "startIndex": 0,
        "numPages": 0,
        "limit": 0
    }
}

Activate or deactivate a domain

Update the activation status of a domain.

Endpoint:

PUT /api/v1/domains/:domainId/activation

Parameters:

Name	Type	From	Description
domainId	number	path	The ID of the domain

Request body:

{
    "active": false
}

Example response:

{
    "error": false,
    "status": 200,
    "message": "string",
    "errors": [
        {}
    ],
    "data": {
        "id": 0,
        "name": "Any domain",
        "description": "Any description",
        "subDomains": [
            "string"
        ],
        "parentId": 0,
        "createdAt": "1970-01-01T00:00:00Z",
        "updatedAt": "1970-01-01T00:00:00Z",
        "active": false
    },
    "pagination": {
        "hasPreviousPage": true,
        "hasNextPage": true,
        "previousPage": 0,
        "nextPage": 0,
        "recordsTotal": 0,
        "currentPage": 0,
        "startIndex": 0,
        "numPages": 0,
        "limit": 0
    }
}

User management within domains

Get users of a domain

Retrieve users associated with a domain.

Endpoint:

GET /api/v1/domains/:domainId/users

Parameters:

Name	Type	From	Description
domainId	number	path	The ID of the domain

Example response:

{
    "error": false,
    "status": 200,
    "message": "string",
    "errors": [
        {}
    ],
    "data": [
        {
            "id": 1,
            "username": "username",
            "lastName": "last_name",
            "firstName": "first_name",
            "email": "email@datascend.net"
        }
    ],
    "pagination": {
        "hasPreviousPage": true,
        "hasNextPage": true,
        "previousPage": 0,
        "nextPage": 0,
        "recordsTotal": 0,
        "currentPage": 0,
        "startIndex": 0,
        "numPages": 0,
        "limit": 0
    }
}

Add a user to a domain

Add a user to a domain.

Endpoint:

POST /api/v1/domains/:domainId/users/:userId

Parameters:

Name	Type	From	Description
domainId	number	path	The ID of the domain
userId	number	path	The ID of the user

Example response:

{
    "error": false,
    "status": 200,
    "message": "string",
    "errors": [
        {}
    ],
    "data": [
        {
            "id": "1",
            "email": "email@datascend.net",
            "username": "username",
            "createdAt": "2022-01-05T16:27:16.560Z",
            "updatedAt": "2022-01-05T16:27:16.560Z",
            "deletedAt": "2022-01-05T16:27:16.560Z",
            "active": true,
            "firstName": "first_name",
            "lastName": "last_name",
            "assistant": "",
            "assistantPhone": "",
            "description": "description",
            "salutation": "salutation",
            "title": "title",
            "doNotCall": false,
            "department": 1,
            "addresses": [
                {
                    "id": 18,
                    "street": "street",
                    "city": "city",
                    "state": "state",
                    "postalcode": "postal_code",
                    "country": "country",
                    "userId": 25
                }
            ],
            "phones": [
                {
                    "id": 1,
                    "phoneTypeId": "2",
                    "phoneNumber": "1234",
                    "active": true,
                    "typeDescription": "description",
                    "userId": 1
                }
            ],
            "createdBy": "0",
            "modifiedUserId": "0",
            "photo": "undefined"
        }
    ],
    "pagination": {
        "hasPreviousPage": true,
        "hasNextPage": true,
        "previousPage": 0,
        "nextPage": 0,
        "recordsTotal": 0,
        "currentPage": 0,
        "startIndex": 0,
        "numPages": 0,
        "limit": 0
    }
}

Delete a user from a domain

Remove a user from a domain.

Endpoint:

DELETE /api/v1/domains/:domainId/users/:userId

Parameters:

Name	Type	From	Description
domainId	number	path	The ID of the domain
userId	number	path	The ID of the user

Example response:

{
    "error": false,
    "status": 200,
    "message": "string",
    "errors": [
        {}
    ],
    "data": [
        {
            "id": "1",
            "email": "email@datascend.net",
            "username": "username",
            "createdAt": "2022-01-05T16:27:16.560Z",
            "updatedAt": "2022-01-05T16:27:16.560Z",
            "deletedAt": "2022-01-05T16:27:16.560Z",
            "active": true,
            "firstName": "first_name",
            "lastName": "last_name",
            "assistant": "",
            "assistantPhone": "",
            "description": "description",
            "salutation": "salutation",
            "title": "title",
            "doNotCall": false,
            "department": 1,
            "addresses": [
                {
                    "id": 18,
                    "street": "street",
                    "city": "city",
                    "state": "state",
                    "postalcode": "postal_code",
                    "country": "country",
                    "userId": 25
                }
            ],
            "phones": [
                {
                    "id": 1,
                    "phoneTypeId": "2",
                    "phoneNumber": "1234",
                    "active": true,
                    "typeDescription": "description",
                    "userId": 1
                }
            ],
            "createdBy": "0",
            "modifiedUserId": "0",
            "photo": "undefined"
        }
    ],
    "pagination": {
        "hasPreviousPage": true,
        "hasNextPage": true,
        "previousPage": 0,
        "nextPage": 0,
        "recordsTotal": 0,
        "currentPage": 0,
        "startIndex": 0,
        "numPages": 0,
        "limit": 0
    }
}

Entity management within domains

Move an entity record to a new domain

Moves an entity record from its current domain to another.

Endpoint:

PUT /api/v1/entities/:entity/:id/domain?version=:version

Parameters:

Name	Type	From	Description
version	string	query	The version of the application.
entity	string	path	The name of the entity.
id	number	path	The ID of the entity.

Request Body:

{
    "newDomain": 1
}

Example response:

{
    "error": false,
    "status": 200,
    "message": "string",
    "errors": [
        {}
    ],
    "data": {
        "id": 0,
        "domain": 1,
        "createdBy": "string",
        "updatedBy": "string",
        "dateUpdated": "string",
        "dateCreated": "string",
        "securityGroup": "string",
        "data": {
            "additionalProp1": "string",
            "additionalProp2": "string",
            "additionalProp3": "string"
        }
    },
    "pagination": {
        "hasPreviousPage": true,
        "hasNextPage": true,
        "previousPage": 0,
        "nextPage": 0,
        "recordsTotal": 0,
        "currentPage": 0,
        "startIndex": 0,
        "numPages": 0,
        "limit": 0
    }
}

Domain management on roles

Get domains for a role

Retrieves the domains associated with a specific role.

Endpoint:

GET /api/v1/roles/:roleId/domains?page=1&limit=10

Parameters:

Name	Type	From	Description
roleId	string	path	The ID of the role.
page	number	query	For pagination.
limit	number	query	The number of results per page.

Example response:

{
    "error": false,
    "status": 200,
    "message": "string",
    "errors": [
        {}
    ],
    "data": [
        {
            "id": 0,
            "parentId": 0,
            "totalCount": "1",
            "name": "Any domain",
            "description": "Any description"
        }
    ],
    "pagination": {
        "hasPreviousPage": true,
        "hasNextPage": true,
        "previousPage": 0,
        "nextPage": 0,
        "recordsTotal": 0,
        "currentPage": 0,
        "startIndex": 0,
        "numPages": 0,
        "limit": 0
    }
}

Add a domain to a role

Adds a specified domain to a role.

Endpoint:

PUT /api/v1/roles/:roleId/domains/:domainId

Parameters:

Name	Type	From	Description
roleId	string	path	The ID of the role.
domainId	string	path	The ID of the domain to be added.

Example response:

{
    "error": false,
    "status": 200,
    "message": "string",
    "errors": [
        {}
    ],
    "data": [
        {
            "id": 0,
            "parentId": 0,
            "totalCount": "1",
            "name": "Any domain",
            "description": "Any description"
        }
    ],
    "pagination": {
        "hasPreviousPage": true,
        "hasNextPage": true,
        "previousPage": 0,
        "nextPage": 0,
        "recordsTotal": 0,
        "currentPage": 0,
        "startIndex": 0,
        "numPages": 0,
        "limit": 0
    }
}

Delete a domain from a role

Deletes a specific domain from a role.

Endpoint:

DELETE /api/v1/roles/:roleId/domains/:domainId

Parameters:

Name	Type	From	Description
roleId	string	path	The ID of the role.
domainId	string	path	The ID of the domain to be deleted.

Example response:

{
    "status": 200,
    "error": false,
    "message": "string",
    "data": [
        {}
    ]
}

Domain management on users

Get domains for a user

Retrieves a list of domains associated with a specific user.

Endpoint:

GET /api/v1/users-data/:userId/domains

Parameters:

Name	Type	From	Description
userId	string	path	The ID of the user.

Example response:

{
    "error": false,
    "status": 200,
    "message": "string",
    "errors": [
        {}
    ],
    "data": [
        1
    ],
    "pagination": {
        "hasPreviousPage": true,
        "hasNextPage": true,
        "previousPage": 0,
        "nextPage": 0,
        "recordsTotal": 0,
        "currentPage": 0,
        "startIndex": 0,
        "numPages": 0,
        "limit": 0
    }
}

Toggle a domain for a user

Toggles a domain for a specific user, which typically means adding it if it doesn’t exist or removing it if it does.

Endpoint:

PATCH /api/v1/users-data/:userId/domains/:domain

Parameters:

Name	Type	From	Description
userId	string	path	The ID of the user.
domain	string	path	The domain to be toggled.

Example response:

{
    "id": "2",
    "userId": "1",
    "domainId": "1"
}