Page MenuHomeVyOS Platform

Define a high level HTTP API
Closed, ResolvedPublic

Description

Right now we have a low level HTTP API that allows creating/deleting config nodes with given paths. The bad thing is that the user needs to know the config syntax.
Config syntax isn't exactly constant either—we sometimes change it between LTS releases.

This is bad for development of management tools. Our plan for the local web GUI is to provide a simplified interface for novice users and helpdesk personnel, for example. Other people may want to develop tools similar in spirit but different in their look or behaviour.

It would be handy to have a more high level API that is relatively abstract and doesn't depend on precise config syntax. For example: /firewall/rule/create/ with abstract POST data.

We need to first define endpoints, then actually implement them.

Details

Version
-
Is it a breaking change?
Perfectly compatible
Issue type
Feature (new functionality)

Related Objects

Event Timeline

Coming with a syntax which is not ultimately going to be as complex as the cli may be an impossible challenge. Changing the API to include in the XML what is path vs payload may indeed lead to indeed a better API tho. The example given use the word create in the path when REST would use POST.

Another way to not break precious API code may be to version the API, and have the migration code able to convert a request to the latest syntax.

A simple experiment using GraphQL to configure a DHCP server is here:
https://github.com/vyos/vyos-1x/compare/current...jestabro:graphql

This requires support from:
https://github.com/jestabro/vyos-http-api-tools/tree/graphql

cf. README.graphql in vyos-1x.

erkin set Issue type to Feature (new functionality).Aug 29 2021, 1:33 PM
erkin removed a subscriber: Global Notifications.

+1; versioning the API is also a best practice.

dmbaturin triaged this task as Normal priority.Jan 9 2024, 8:03 PM
dmbaturin edited projects, added VyOS 1.5 Circinus; removed VyOS 1.3 Equuleus (1.3.6).
syncer claimed this task.
syncer removed a project: VyOS 1.5 Circinus.

The only piece missing from the original design of using GraphQL to implement templated high level configurations is: migration of templates, versioned by component version; the recent addition of the convertor of set commands to config trees (T6740) makes this a simpler problem. I will revisit and implement migration of templated configurations.

Currently I believe that the GraphQL api doesn't offer much functionality unless that has changed over the most recent 3-4 months. I believe it only had get functions and maybe 2 or 3 set methods. This is blocking the web api as it was decided to use GQL for the API.