Extend the capabilities of dynamic REST API serialization to incorporate downstream relations

[jeremystretch]

NetBox version

v4.1.6

Feature type

New functionality

Triage priority

I volunteer to perform this work (if approved)

Proposed functionality

NetBox v4.0 introduced support for dynamic serializer fields in the REST API. For example, a request for GET /api/dcim/sites/?fields=id,name,status will return only the listed fields for each site:

{
    "count": 24,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 24,
            "name": "Butler Communications",
            "status": {
                "value": "active",
                "label": "Active"
            }
        },
        {
            "id": 2,
            "name": "DM-Akron",
            "status": {
                "value": "active",
                "label": "Active"
            }
        },
        ...
    ]
}

Now that this mechanism is in place, we can extend REST API serializers to also support returning downstream-related objects (e.g. racks or devices within a site). These objects will not be part of the object representation by default, but can be enabled by inclusion in the fields query parameter as above.

For example, retrieving a list of device interfaces along with their assigned IP addresses could be achieved by requesting GET /api/dcim/interfaces/?device=123&fields=name,type,enabled,ip_addresses, which return something like the following rough mock-up:

{
    "count": 14,
    "next": null,
    "previous": null,
    "results": [
        {
            "name": "GigabitEthernet0/0/0",
            "type": {
                "value": "1000base-x-sfp",
                "label": "SFP (1GE)"
            },
            "enabled": true,
            "ip_addresses": [
                {
                    "id": 31,
                    "display": "172.16.0.1/24",
                    "family": {
                        "value": 4,
                        "label": "IPv4"
                    },
                    "address": "172.16.0.1/24",
                }
            ]
        },
    ...
    ]
}

Use case

This would provide more flexibility when consuming the REST API, affording the API client a limited ability to include immediately related objects and obviate the need (in some cases) to make additional requests.

While it should be pointed out that this FR does not seek to effectively replicate the full GraphQL API in REST form, it would likely serve many of the simpler use cases for GraphQL.

Database changes

N/A

External dependencies

N/A

[julianstolp]

Hi Jeremy, I really like this idea. Just a quick question, in your example would the full IP address object be returned in a similar way to /api/ipam/ip-addresses/1/ or just what would be visible in the UI? This is interesting to me as we use a lot of object-based permissions for other users.