JSON API - Roles

  • Updated

NimblexHCBanner.png

This page explains the API functions for the querying and updating of roles within your Nimblex system.

Roles are polymorphic, where a role is one of: user, group or guest. This will be represented as type field values of: user, group or guest.

List Roles

Get a list of all roles in the system.

GET @apiroot/roles

Example Request

EMPTY

Example Response

{
    "data": [
		{
			"type": "user", /* user, guest or group */
			"id": "jjones", // rolename
		},
		{
			"type": "group",
			"id": "Administrators",
		}
	]
}

Read Role

GET @apiroot/roles/{urlencoded rolename}

Example Request

EMPTY
 Example Response
{
    "data": {
        "type": "user", /* user, guest or group */
        "id": "jjones", // rolename
        "links": {
            "self": "@apiroot/roles/jjones"
        },
        "relationships": {
            "department": {
                "links": {
                    "self": "@apiroot/roles/jjones/relationships/department",
                    "related": "@apiroot/departments/departmentname"
                }
            },
            "supervisor": {
                "links": {
                    "self": "@apiroot/roles/jjones/relationships/supervisor",
                    "related": "@apiroot/roles/mysupervisorsrolename"
                }
            },
            "parents": {
                "links": {
                    "self": "@apiroot/roles/jjones/relationships/parents"
                }
            },
            "children": {
                "links": {
                    "self": "@apiroot/roles/jjones/relationships/children"
                }
            }
        },
        "attributes": {
            "displayName": "John Jones",
            "email": "john@mars.com",
            "position": "Team Leader",   // must be a valid position value
            "approvalLimit": 1234,       // not supported for groups
            "expiryDate": "2016-01-01",  // not supported for groups
            "enabled": true              // not supported for groups
        }
    }
}
Record, folder or file does not exist:
404 Not Found (EMPTY)

Create Role

POST @apiroot/roles

Example Request

{
    "data": {
        "type": "user", /* user, guest or group */
        "id": "jjones", // rolename, required
        "attributes": {
            "displayName": "John Jones",
            "email": "john@mars.com",
            "position": "Team Leader",   // must be a valid position value
            "approvalLimit": 1234,       // not supported for groups
            "expiryDate": "2016-01-01",  // not supported for groups
            "enabled": true              // not supported for groups
        }
    }
}

Example Response

{
    "data": {
        "type": "user",
        "id": "jjones", // rolename
        "links": {
            "self": "@apiroot/roles/jjones",   
        }
    }
}

Update Role

PATCH @apiroot/roles/jjones

Example Request

{
    "data": {
        "type": "user", /* user, guest or group, this is mandatory according to JSON API */
        "attributes": {
            "displayName": "John Jones",
            "email": "john@mars.com",
            "position": "position",
            "approvalLimit": 1234,       // not supported for groups
            "expiryDate": "2016-01-01",  // not supported for groups
            "enabled": true              // not supported for groups
        }
    }
}
Example Response

Success:

200 Success EMPTY

No such role:

404 Not Found EMPTY

Delete Role

DELETE @apiroot/roles/{urlencoded rolename}

Example Request

EMPTY

Example Response

Success:

200 Success EMPTY
No such role:
404 Not Found EMPTY

Get Role Department

GET @apiroot/roles/{urlencoded rolename}/relationships/department

Example Request

EMPTY

Example Response

Member of a department:

{
    "data": {
        "type": "department",
        "id": "Accounts"
    }
}
Not a member of a department:
{
    "data": null
}

Update/Remove Role Department

PATCH @apiroot/roles/{urlencoded rolename}/relationships/department

Set Department

Example Request

{
    "data": {
        "type": "department",
        "id": "Accounts"
    }
}

Example Response

Success:
200 Success EMPTY

No such user:
404 Not Found EMPTY

Clear Department

Example Request

{
    "data": null
}

Example Response

Success:

200 Success EMPTY

No such user:

404 Not Found EMPTY

Get Role Supervisor

GET @apiroot/roles/{urlencoded rolename}/relationships/supervisor

Example Request

EMPTY

Example Response

Has a supervisor:

{
    "data": {
        "type": "user",
        "id": "smurray"
    }
}
 Has no supervisor:
{
    "data": null
}

Update/Remove Role Supervisor

PATCH @apiroot/roles/{urlencoded rolename}/relationships/supervisor

Set Supervisor

Example Request

{
    "data": {
        "type": "supervisor",
        "id": "smurray"
    }
}

Example Response

Success:

200 Success EMPTY
No such user:
404 Not Found EMPTY

Clear Supervisor

Example Request

{
    "data": null
}

Example Response

Success:

200 Success EMPTY

No such user:

404 Not Found EMPTY