GraphQL support

[cimnine]

Issue type

[X] Feature request
[ ] Bug report
[ ] Documentation

Environment

• Python version: 3
• NetBox version: 2.2

Description

I've talked about it a while back, but it came up in a different context in the networktocode#netbox slack channel recently.

Joey Wilhelm [20:13 Uhr] On a related note, returning related objects sounds like a case to look to GraphQL...
jstretch [20:16 Uhr] what would GraphQL solve?
Joey Wilhelm [20:23 Uhr] You're able to retrieve exactly what you want from an API call, and only what you want. So you can request related objects 5 levels down, or just 2 attributes off the object you're querying (bearbeitet)
jstretch [20:24 Uhr] ah
Joey Wilhelm [20:24 Uhr] So the API user defines what data they want in the response, rather than the API defining that
jstretch [20:26 Uhr] https://github.com/graphql-python/graphene-django
jstretch [20:26 Uhr] wonder how involved that is to get going

We've implemented a Netbox integration for GraphQL a while back, but we're not able to maintain it at the moment. It's called django-netbox-graphql. Right now, it's built as a django module that can be plugged into Netbox quite easily. So it should be straight-forward to get going.

Some features:

• GraphQL representations of the most important entities
• GraphQL representations of some complex entities.
• Lots of unit tests
• Graph_i_QL: Visual GraphQL editor. ("The swagger for GraphQL")

Whats the case for GraphQL?

GraphQL is a "new" way to consume from a remote system. In contrast to REST, where there is a route for every resource, GraphQL only knows one route. The request to that route contains a query in a well-defined format. In the query the requesting application specifies which resources it would like to consume and, and this is essential, which objects it would like to have nested.

A short example
I would like to get all IPs of pool subnets and their corresponding MAC addresses to write them into a DHCP config file.

With REST

• I would first query the subnets endpoint and filter for pool subnets.
• Then I'd have to get a list of all IPs from the returned subnets. That's one query per subnet.
• I get the MAC Address from the embedded interface object. But I also get a lot of unrelated information.

With GraphQL

I would have to write one query that returns exactly the fields I need. It would look like this:

{
  prefixes(is_pool: true) {
    id
    family
    prefix
    ip_addresses {
      address
      interface {
        mac_address
      }
    }
  }
}

(Note: This query does not work yet with django-netbox-graphql!)

Conclusion

I understand, that this feature is no priority for Netbox. Also, the Netbox REST API is very powerful and already nests a lot of important information. But I also think that people want Netbox to become their single-source-of-truth for all kinds of information related to devices on their network. A versatile query language, that offers full flexibility and reduces requests to Netbox might be required in such a future.

[jeremystretch]

I'd also like to explore this at some point, but I have to close this out as our current policy does not allow for any new major feature requests until the backlog of existing requests has been worked through.

[cimnine]

We've started an integration of GraphQL into Netbox a while back. It worked great for all implemented queries. Unfortunately we can't maintain it anymore, because we never got to use it. But it might still serve as reference should someone else ever see the huge benefit over static REST APIs and decide to either maintain the project in a fork or integrate it into Netbox.

https://github.com/ninech/django-netbox-graphql/

[mraerino]

I'd also like to explore this at some point, but I have to close this out as our current policy does not allow for any new major feature requests until the backlog of existing requests has been worked through.

@jeremystretch at what point is it possible to reopen this issue?

[jeremystretch]

Re-opening this as a candidate for v3.0.

[ryanmerolle]

I think MVP release for GraphQL should focus on READ / GET only since that is where most people have headaches with REST / post GET data manipulations.

Sure there would be some interesting write/updates using GraphQL, but I am doubtful the ROI is as high. It also allows you to iterate on the integration with a limited scope.

[ziggekatten]

Agree with ryanmerolle. Biggest gains are by far the GET requests.