diff options
| -rw-r--r-- | src/services/api/graphql/README.graphql | 112 |
1 files changed, 112 insertions, 0 deletions
diff --git a/src/services/api/graphql/README.graphql b/src/services/api/graphql/README.graphql new file mode 100644 index 000000000..8414e795a --- /dev/null +++ b/src/services/api/graphql/README.graphql @@ -0,0 +1,112 @@ + +Example using GraphQL mutations to configure a DHCP server: + +This assumes that the http-api is running: + +'set service https api' + +One can configure an address on an interface, and configure the DHCP server +to run with that address as default router by requesting these 'mutations': + +mutation { + createInterfaceEthernet (data: {interface: "eth1", + address: "192.168.0.1/24", + description: "BOB"}) { + success + errors + data { + address + } + } +} + +mutation { + createDhcpServer(data: {sharedNetworkName: "BOB", + subnet: "192.168.0.0/24", + defaultRouter: "192.168.0.1", + dnsServer: "192.168.0.1", + domainName: "vyos.net", + lease: 86400, + range: 0, + start: "192.168.0.9", + stop: "192.168.0.254", + dnsForwardingAllowFrom: "192.168.0.0/24", + dnsForwardingCacheSize: 0, + dnsForwardingListenAddress: "192.168.0.1"}) { + success + errors + data { + defaultRouter + } + } +} + +These requests can be set in the GraphQL playground, or made with curl: + +curl -k -H 'Content-Type: application/json' -d '{"query": "{hello}"}' https://{{ host_address }}/graphql + +replacing the query with the above mutations as JSON. + +What's here: + +services +├── api +│ └── graphql +│ ├── graphql +│ │ ├── directives.py +│ │ ├── __init__.py +│ │ ├── mutations.py +│ │ └── schema +│ │ ├── dhcp_server.graphql +│ │ ├── interface_ethernet.graphql +│ │ └── schema.graphql +│ ├── recipes +│ │ ├── dhcp_server.py +│ │ ├── __init__.py +│ │ ├── interface_ethernet.py +│ │ ├── recipe.py +│ │ └── templates +│ │ ├── dhcp_server.tmpl +│ │ └── interface_ethernet.tmpl +│ └── state.py +├── vyos-configd +├── vyos-hostsd +└── vyos-http-api-server + +The GraphQL library that we are using, Ariadne, advertises itself as a +'schema-first' implementation: define the schema; define resolvers +(handlers) for declared Query and Mutation types (Subscription types are not +currently used). + +In the current approach to a high-level API, we consider the +Jinja2-templated collection of configuration mode 'set'/'delete' commands as +the Ur-data; the GraphQL schema is produced from those files, located in +'api/recipes/templates'. + +Resolvers for the schema Mutation fields are dynamically generated using a +'directive' added to the respective schema field. The directive, +'@generate', is handled by the class 'DataDirective' in +'api/graphql/directives.py', which calls the 'make_resolver' function in +'api/graphql/mutations.py'; the produced resolver calls the appropriate +wrapper in 'api/recipes', with base class doing the (overridable) +configuration steps of calling all defined 'set'/'delete' commands. + +Integrating the above with vyos-http-api-server is ~10 lines of code. + +What needs to be done: + +• automate generation of schema and wrappers from templated configuration +commands + +• investigate whether the inversion of control provided by the named +wrappers in 'api/recipes' is sufficient for use cases which need to modify +data + +• encapsulate the manipulation of 'canonical names' which transforms the +prefixed camel-case schema names to various snake-case file/function names + +• consider mechanism for migration of templates: offline vs. on-the-fly + +• define the naming convention for those schema fields that refer to +configuration mode parameters: e.g. how much of the path is needed as prefix +to uniquely define the term |