[GH-ISSUE #461] Benefits of a REST-based API specification #839

Closed
opened 2026-08-05 00:40:07 -04:00 by saavagebueno · 7 comments
Owner

Originally created by @Natureshadow on GitHub (Sep 10, 2022).
Original GitHub issue: https://github.com/netbirdio/netbird/issues/461

I would like to make a point for reconsidering the choice of API for the communication between the agent and the management service, which uses gRPC currently.

It would be beneficial to use a REST-based approach. Netbird's core conecpt is an ideal addition to enterprise platforms that rely on REST APIs. For example, it would be possible to write a Nextcloud app integrating self-service VPN in Nextcloud, or in AlekSIS for schools. These backends would integrate the REST API for NetBird into their set of APIs, and integrate with information managed by them directly. AlekSIS could, for example, directly turn information like "which students can access the internet", "which students' lent devices can talk to each other when taken home" into NetBird host configuration.

Thus, I would like to see a REST interface added to the management service, ideally with a well-drafted OpenAPI specification that can be re-used by alternative backend implementations.

Originally created by @Natureshadow on GitHub (Sep 10, 2022). Original GitHub issue: https://github.com/netbirdio/netbird/issues/461 I would like to make a point for reconsidering the choice of API for the communication between the agent and the management service, which uses gRPC currently. It would be beneficial to use a REST-based approach. Netbird's core conecpt is an ideal addition to enterprise platforms that rely on REST APIs. For example, it would be possible to write a Nextcloud app integrating self-service VPN in Nextcloud, or in AlekSIS for schools. These backends would integrate the REST API for NetBird into their set of APIs, and integrate with information managed by them directly. AlekSIS could, for example, directly turn information like "which students can access the internet", "which students' lent devices can talk to each other when taken home" into NetBird host configuration. Thus, I would like to see a REST interface added to the management service, ideally with a well-drafted OpenAPI specification that can be re-used by alternative backend implementations.
saavagebueno added the feature-request label 2026-08-05 00:40:07 -04:00
Author
Owner

@braginini commented on GitHub (Sep 10, 2022):

Hey @Natureshadow
Thank you for the feedback!

I think that we already have what you are asking for :)

We have two APIs: gRPC and HTTP.

Our gRPC API is between NetBird Agents and the Management service to keep agents in sync with the network changes. Simply put, it is an internal API that makes the mesh network.

The HTTP API is a management API that allows it to create ACL rules, routes, etc. In other words, to control the network. NetBird's Dashboard uses it from the React SPA. I think this is the one you are asking for.
Here is the OpenAPI specification. We didn't publish any docs yet, but we will. There is some work to do on it :)
https://github.com/netbirdio/netbird/blob/main/management/server/http/api/openapi.yml

There is one caveat, though. We don't expose any API Keys yet, but I can explain how to work around it if you want to try.

<!-- gh-comment-id:1242785025 --> @braginini commented on GitHub (Sep 10, 2022): Hey @Natureshadow Thank you for the feedback! I think that we already have what you are asking for :) We have two APIs: gRPC and HTTP. Our **gRPC API** is between NetBird Agents and the Management service to keep agents in sync with the network changes. Simply put, it is an internal API that makes the mesh network. The **HTTP API** is a management API that allows it to create ACL rules, routes, etc. In other words, to control the network. NetBird's Dashboard uses it from the React SPA. I think this is the one you are asking for. Here is the OpenAPI specification. We didn't publish any docs yet, but we will. There is some work to do on it :) https://github.com/netbirdio/netbird/blob/main/management/server/http/api/openapi.yml There is one caveat, though. We don't expose any API Keys yet, but I can explain how to work around it if you want to try.
Author
Owner

@Natureshadow commented on GitHub (Sep 10, 2022):

The HTTP API is a management API that makes it possible to create ACL rules, routes etc. NetBird's Dashboard uses it from the React SPA. I think this is the one you are asking for.

No.

As I said, I am talking about the API between the agents and the management service.

The goal is to let the netbird agent talk to a different management service implementation, and allow other vendors to implement a netbird-compatible management backend.

10 Sep 2022 20:39:49 Misha Bragin @.***>:

The HTTP API is a management API that makes it possible to create ACL rules, routes etc. NetBird's Dashboard uses it from the React SPA. I think this is the one you are asking for.

<!-- gh-comment-id:1242793536 --> @Natureshadow commented on GitHub (Sep 10, 2022): > The *HTTP API* is a management API that makes it possible to create ACL rules, routes etc. NetBird's Dashboard uses it from the React SPA. I think this is the one you are asking for. No. As I said, I am talking about the API between the agents and the management service. The goal is to let the netbird agent talk to a different management service implementation, and allow other vendors to implement a netbird-compatible management backend. 10 Sep 2022 20:39:49 Misha Bragin ***@***.***>: > The *HTTP API* is a management API that makes it possible to create ACL rules, routes etc. NetBird's Dashboard uses it from the React SPA. I think this is the one you are asking for.
Author
Owner

@braginini commented on GitHub (Sep 10, 2022):

@Natureshadow I see, I misunderstood you.

I like the idea! But this would be quite an effort.
Agents use gRPC streams that maintain a connection to the Management service. The closes alternative I see is a websocket. To be REST compatible some polling mechanism should be implemented.

Then all the logic of access controls, routing, device registration, etc should be implemented in that backend.

Wouldn't it be easier to integrate with the Management service?

<!-- gh-comment-id:1242807965 --> @braginini commented on GitHub (Sep 10, 2022): @Natureshadow I see, I misunderstood you. I like the idea! But this would be quite an effort. Agents use gRPC streams that maintain a connection to the Management service. The closes alternative I see is a websocket. To be REST compatible some polling mechanism should be implemented. Then all the logic of access controls, routing, device registration, etc should be implemented in that backend. Wouldn't it be easier to integrate with the Management service?
Author
Owner

@Natureshadow commented on GitHub (Sep 12, 2022):

Wouldn't it be easier to integrate with the Management service?

It depends.

Federation between different services can be tricky, and keeping information in sync can be costly.

Also, REST has its own benefits over gRPC: It uses short-lived requests.

The environments that we are targeting, both in the educational area and for companies, work best if they depend only on short-lived requests, and regular HTTP requests. Think of restrictive/broken public WiFi connections. The ultimate goal, in a very condensed form, is: Provide a fully functional client system that has user authentication, device/configuration/software management, and VPN management, and does not need anything more than simple HTTP requests to one single specific endpoint.

Considering that, gRPC is in itself a questionable choice for retrieving configuration information from a server, in my opinion.

<!-- gh-comment-id:1243644087 --> @Natureshadow commented on GitHub (Sep 12, 2022): > Wouldn't it be easier to integrate with the Management service? It depends. Federation between different services can be tricky, and keeping information in sync can be costly. Also, REST has its own benefits over gRPC: It uses short-lived requests. The environments that we are targeting, both in the educational area and for companies, work best if they depend only on short-lived requests, and regular HTTP requests. Think of restrictive/broken public WiFi connections. The ultimate goal, in a very condensed form, is: Provide a fully functional client system that has user authentication, device/configuration/software management, and VPN management, and does not need anything more than simple HTTP requests to one single specific endpoint. Considering that, gRPC is in itself a questionable choice for retrieving configuration information from a server, in my opinion.
Author
Owner

@braginini commented on GitHub (Sep 14, 2022):

Got your point @Natureshadow
This is definitely worth a design review. I can't promise that we will start working on it very soon since it involves lots of parts.

<!-- gh-comment-id:1246383039 --> @braginini commented on GitHub (Sep 14, 2022): Got your point @Natureshadow This is definitely worth a design review. I can't promise that we will start working on it very soon since it involves lots of parts.
Author
Owner

@Natureshadow commented on GitHub (Oct 11, 2022):

This is definitely worth a design review. I can't promise that we will start working on it very soon since it involves lots of parts.

Yep, it's certainly not simple.

Thanks for considering!

<!-- gh-comment-id:1274398989 --> @Natureshadow commented on GitHub (Oct 11, 2022): > This is definitely worth a design review. I can't promise that we will start working on it very soon since it involves lots of parts. Yep, it's certainly not simple. Thanks for considering!
Author
Owner

@PizzaLovingNerd commented on GitHub (May 28, 2026):

Hello, we are closing this issue. We are trying to consolidate our issues, and this issue is coming up on 4 years old and still is a huge thing to implement.

Since this issue was opened the Management REST API has matured a lot, and can cover a lot of use-cases described here.

If you are still interested can you please open a GitHub Discussion? Thanks!

<!-- gh-comment-id:4567679792 --> @PizzaLovingNerd commented on GitHub (May 28, 2026): Hello, we are closing this issue. We are trying to consolidate our issues, and this issue is coming up on 4 years old and still is a huge thing to implement. Since this issue was opened the Management REST API has matured a lot, and can cover a lot of use-cases described here. If you are still interested can you please open a [GitHub Discussion](https://github.com/netbirdio/netbird/discussions)? Thanks!
Sign in to join this conversation.
No Label feature-request
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: DYNR/netbird#839