Re: [Apiman-user] Enhancing apiman-cli to make headless gateway configs easier to use.

Here's a preview of my proposed data format -- it reuses the format and model developed by Pete Cornish and his team; big kudos to them! [1]. I'm soliciting suggestions and comments, feel free to reply here (or reach out privately if that's not possible). Example: apiman-cli gateway apply -f /Users/msavy/tmp/sample.yaml ``` # sample.yaml --- system: gateways: - name: "test-gw" type: "REST" config: endpoint: "http://localhost:8080/apiman-gateway-api" username: "apimanager" password: "apiman123!" plugins: - name: TestPolicyFriendlyName // (1) groupId: "io.apiman.plugins" artifactId: "apiman-plugins-test-policy" version: "1.3.1.Final" org: name: "test" apis: - name: "example" version: "1.0" config: endpoint: "http://localhost:8080/services/echo" endpointType: "rest" public: true gateway: "test-gw" policies: - name: "CachingPolicy" // (2) config: ttl: 60 - plugin: TestPolicyFriendlyName // (3) config: foo: 123 ``` (1) Friendly name for plugin instead of having to refer to it by full GAV (2) In-built policy will be looked up to ensure it exists and resolves the correct FQCN. (3) Add a policy by plugin friendly name (else GAV) One rare edge case when multiple policies are defined in a single plugin. In that situation we allow disambiguation by providing the plugin's `id` in the `name`/`id` field: ``` <SNIP> policies: - name: PolicyOne plugin: PluginWithMultiplePolicies config: foo: 123 ``` Thoughts? Feedback? Still a bit of work to do before it's PR-ready but making some progress. Regards, Marc [1] With one tiny addition. On 7 July 2017 at 14:29, Marc Savy <marc.savy(a)redhat.com&gt; wrote: > We've had some people using the Apiman Gateway headless for a while > now, either with the new immutable registry that loads from JSON[1], > or simply using any existing registry via the gateway API instead of > using a manager. > > The main issue people encounter is that policy configuration contains > two fields that are difficult to work out and clumsy to encode > properly[1]: > > - `policyImpl` requires the plugin's URI, including the path to its > main class. You can work these out by looking at the plugin's source > code, but that's rather circuitous and it would be nicer to just > provide the plugin's GAV (like in the manager) and for it to be > resolved. > > - `policyJsonConfig`[3] needs to be escaped properly (and must valid > according to its schema). > > Neither of these aspects are especially user-friendly. My proposal is > to extend apiman-cli's functionality to allow the Apiman Gateway to be > configured directly via a YAML/JSON file (i.e. declaratively). > > We can therefore provide a more user-friendly interface that automates > the resolution of plugins; validations and escapes the policy config; > etc. > > A final step would be to bundle the apiman-cli tool with our distros > to make it easier to access. > > Any thoughts? > > Regards, > Marc > > [1] https://apiman.gitbooks.io/apiman-installation-guide/ installation-guide/vertx/download.html#_elasticsearch > [2] Of course, this interface was never truly designed to be used by > humans, so that's understandable > [3] Unfortunately named as it can be any arbitrary string, the policy > just needs to be able to decode it. For example, it could be XML.