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

Here's the PR for those who want to track progress: https://github.com/apiman/apiman-cli/pull/27 On 18 July 2017 at 23:34, Marc Savy <marc.savy(a)redhat.com&gt; wrote: > > 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/v... > > [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.