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

[Marc Savy]

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.