Page MenuHomeVyOS Platform
Create Task
Maniphest T2768

Define a high level HTTP API
Open, NormalPublic
Actions

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

Difficulty level
Unknown (require assessment)
Version
-
Why the issue appeared?
Will be filled on close
Is it a breaking change?
Perfectly compatible
Issue type
Feature (new functionality)

Related Objects
Search...

Event Timeline

dmbaturin created this task.Aug 7 2020, 11:33 AM
jack9603301 added a subscriber: jack9603301.Aug 7 2020, 11:41 AM
thomas-mangin added a subscriber: thomas-mangin.Aug 7 2020, 12:40 PM

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.

pasik added a subscriber: pasik.Aug 7 2020, 3:41 PM
jestabro added a subscriber: jestabro.EditedJun 18 2021, 1:49 PM

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: Active contributors.
syncer edited projects, added VyOS 1.3 Equuleus (1.3.0); removed VyOS 1.3 Equuleus.Nov 6 2021, 11:24 AM
jestabro mentioned this in T3993: Extend HTTP API GraphQL support.Nov 15 2021, 5:50 PM
jestabro added a subtask: T3993: Extend HTTP API GraphQL support.
jestabro edited projects, added VyOS 1.3 Equuleus, VyOS 1.4 Sagitta; removed VyOS 1.3 Equuleus (1.3.0).Dec 4 2021, 7:24 PM
jestabro edited projects, added VyOS 1.3 Equuleus (1.3.0); removed VyOS 1.3 Equuleus.Dec 6 2021, 2:22 PM
eronlloyd added a subscriber: eronlloyd.Feb 20 2022, 11:45 AM

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

penetal added a subscriber: penetal.Jul 19 2022, 7:51 PM
syncer edited projects, added VyOS 1.3 Equuleus (1.3.3); removed VyOS 1.3 Equuleus (1.3.0).Aug 29 2022, 7:05 AM
jestabro mentioned this in T4808: Add details of configtree operations to migration log.Nov 8 2022, 4:40 PM
syncer edited projects, added VyOS 1.3 Equuleus (1.3.4); removed VyOS 1.3 Equuleus (1.3.3).Jul 12 2023, 9:41 PM
syncer edited projects, added VyOS 1.3 Equuleus (1.3.5); removed VyOS 1.3 Equuleus (1.3.4).Aug 25 2023, 9:30 PM
syncer edited projects, added VyOS 1.3 Equuleus (1.3.6); removed VyOS 1.3 Equuleus (1.3.5).Dec 17 2023, 11:37 PM
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).
dmbaturin closed subtask T3993: Extend HTTP API GraphQL support as Resolved.Feb 15 2024, 10:53 AM
dmbaturin removed a project: VyOS 1.4 Sagitta.Thu, Apr 11, 3:26 PM