JSON API - Departments

  • Updated

NimblexHCBanner.png

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

Note that a 'department' can be any level of organisation unit, be it: team, service unit, division, organisation, business. Each department has a 'Type' free text field that can be used to differentiate these different levels, and a department may contain other departments.

Departments also feature 3 additional 'OtherN' (other1, other2 and other3) fields for arbitrary data required by specific systems.

List Departments

Get a list of all departments in a system

GET @apiroot/departments

Example Request

EMPTY

Example Response

If there are no departments:

// Status: 200
{
    "data": []
}

If there are some example departments:

// Status: 200
{
    "data": [
        {
            "id": "Example Organisation",
            "type": "department",
            "attributes": {
                "departmentType": "Organisation",
                "description": "",
                "location": "",
                "other1": null,
                "other2": null,
                "other3": null
            },
            "links": {
                "self": "@apiroot/departments/Example%20Organisation"
            }
        },
        {
            "id": "Example Department 1",
            "type": "department",
            "attributes": {
                "departmentType": "Department",
                "description": "",
                "location": "",
                "other1": null,
                "other2": null,
                "other3": null
            },
            "links": {
                "self": "@apiroot/departments/Example%20Department%201"
            }
        },
        {
            "id": "Example Division 1",
            "type": "department",
            "attributes": {
                "departmentType": "Division",
                "description": "",
                "location": "",
                "other1": null,
                "other2": null,
                "other3": null
            },
            "links": {
                "self": "@apiroot/departments/Example%20Division%201"
            }
        },
        {
            "id": "Example Team 1",
            "type": "department",
            "attributes": {
                "departmentType": "Team",
                "description": "",
                "location": "",
                "other1": null,
                "other2": null,
                "other3": null
            },
            "links": {
                "self": "@apiroot/departments/Example%20Team%201"
            }
        }
    ]
}

 

Read Department

Get a list of all departments in a system

GET @apiroot/departments/{urlencoded department name}

Example Request

EMPTY

Example Response

// Status: 200
{
    "data": {
        "id": "Example Organisation",
        "type": "department",
        "attributes": {
            "departmentType": "Organisation",
            "description": "",
            "location": "",
            "other1": "",
            "other2": "",
            "other3": null
        },
        "relationships": {
            "parent": {
                "links": {
                    "self": "@apiroot/departments/Example%20Organisation/relationships/parent"
                }
            }
        }
    }
}

Update Department

Update a single department.

PATCH @apiroot/departments/{urlencoded department name}

Example Request

{
    "data": {
        "type": "department",
        "id": "Example Organisation",
        "attributes": {
            "departmentType": "Organisation",
            "location": "123 Fake street",
            "description": "",
            "other1": "",
            "other2": "",
            "other3": ""
        }
    }
}

Example Response

204 No Content EMPTY

Delete Department

Delete a single department.

DELETE @apiroot/departments/{urlencoded department name}

Example Request

Empty

Example Response

204 No Content EMPTY

Get Parent Department

GET @apiroot/departments/{urlencoded department name}/relationships/parent

Example Request

Empty

Example Response

// Status: 200
{
    "data": {
        "id": "Example Department 1",
        "type": "department",
        "attributes": {
            "departmentType": "Department",
            "description": "",
            "location": "",
            "other1": null,
            "other2": null,
            "other3": null
        }
    }
}

Set/Clear Department Parent

PATCH @apiroot/departments/{urlencoded department name}/relationships/parent

Set Parent

Example Request

{
    "data": {
        "id": "Example Department 1",
        "type": "department"
    }
}

Example Response

204 No Content EMPTY

Clear Parent

Example Request

{
    "data": null
}

Example Response

204 No Content EMPTY