Benefits of a REST-based API specification

[Natureshadow]

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.

[braginini]

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.

[Natureshadow]

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.

[braginini]

@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?

[Natureshadow]

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.

[braginini]

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.

[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.

Yep, it's certainly not simple.

Thanks for considering!