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

[Marc Savy]

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 at redhat.com> 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 at redhat.com> 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.
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/apiman-user/attachments/20170725/96a8eebe/attachment.html