starred/netbox
1
0
Fork 0
mirror of https://github.com/netbox-community/netbox.git synced 2026-01-11 21:10:29 +01:00
Code Issues 273 Packages Projects Releases 10 Wiki Activity

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

New Issue
Open
opened 2025-12-29 21:31:45 +01:00 by adam · 2 comments
adam commented 2025-12-29 21:31:45 +01:00
Owner
Copy Link

Originally created by @jeremystretch on GitHub (Nov 8, 2024).

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

Originally created by @jeremystretch on GitHub (Nov 8, 2024). ### 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
adam added the type: featurenetboxneeds milestonestatus: backlogcomplexity: high labels 2025-12-29 21:31:45 +01:00
adam commented 2025-12-29 21:31:46 +01:00
Author
Owner
Copy Link

@julianstolp commented on GitHub (Nov 11, 2024):

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.

@julianstolp commented on GitHub (Nov 11, 2024): 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.
adam commented 2025-12-29 21:31:47 +01:00
Author
Owner
Copy Link

@github-actions[bot] commented on GitHub (Apr 25, 2025):

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. NetBox is governed by a small group of core maintainers which means not all opened issues may receive direct feedback. Do not attempt to circumvent this process by "bumping" the issue; doing so will result in its immediate closure and you may be barred from participating in any future discussions. Please see our contributing guide.

@github-actions[bot] commented on GitHub (Apr 25, 2025): This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. NetBox is governed by a small group of core maintainers which means not all opened issues may receive direct feedback. **Do not** attempt to circumvent this process by "bumping" the issue; doing so will result in its immediate closure and you may be barred from participating in any future discussions. Please see our [contributing guide](https://github.com/netbox-community/netbox/blob/main/CONTRIBUTING.md).
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
beta
breaking change
complexity: high
complexity: low
complexity: medium
needs milestone
netbox
pending closure
plugin candidate
pull-request
Mirrored from GitHub Pull Request
 severity: high
severity: low
severity: medium
status: accepted
status: backlog
status: blocked
status: duplicate
status: needs owner
status: needs triage
status: revisions needed
status: under review
topic: GraphQL
topic: Internationalization
topic: OpenAPI
topic: UI/UX
topic: cabling
topic: event rules
topic: htmx navigation
topic: industrialization
topic: migrations
topic: plugins
topic: scripts
topic: templating
topic: testing
type: bug
type: deprecation
type: documentation
type: feature
type: housekeeping
type: translation
No Label complexity: high needs milestone netbox status: backlog type: feature
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/netbox#10459
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?