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.

I thought I'd share some of the good progress that has been made in this area: The Apiman CLI tool will now: * Allow Apiman Gateway API to be driven directly. * Expose new Apiman Gateway API "list entity" functions (e.g. list orgs, APIs, Clients, Versions, etc). * List all orgs: apiman-cli gateway organization list * List all APIs in org "test": apiman-cli gateway api list --org test * Directly apply YAML declarations on the Gateway API (with status checks, etc). * Generate Headless Gateway JSON configs from the YAML declaration format. For more detail, see: https://github.com/apiman/apiman-cli/pull/28 On 25 July 2017 at 17:11, Marc Savy <marc.savy(a)redhat.com&gt; wrote: > 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. > >