= Maven Plugin for API Gateway Policy Development :Author: Martin Look :Email: mlook@axway.com :toc: ifndef::env-github[:icons: font] ifdef::env-github[] :outfilesuffix: .adoc :!toc-title: :caution-caption: :fire: :important-caption: :exclamation: :note-caption: :paperclip: :tip-caption: :bulb: :warning-caption: :warning: endif::[] :mvn-plugin-ver: 1.2.1

image:https://img.shields.io/github/license/Axway-API-Management-Plus/apigw-maven-plugin?style=plastic[] image:https://img.shields.io/github/v/release/Axway-API-Management-Plus/apigw-maven-plugin?style=plastic[]

== Start with Why

Working as a team on policy development has some challenges. Even if PolicyStudio supports team development it requires manual effort to manage dependencies and to keep the sources in sync. Using shared policies is done by including source code folders. But there is no defined way of how to locate the folders and how to version the source code (especially if they are located in separate SCM repositories). This also makes it difficult to share policies between different teams or within a community.

Environmentalization is used to develop policies or gateways, independent of the target environment. The configuration is done with ConfigurationStudio as a separate step. But, as it is a GUI based application, detecting unconfigured fields is a manual and error prone process. Configuration issues are detected at runtime and not at build time.

The goal of this project is to make the life of a policy developer and gateway administrator easier by extending the power of https://maven.apache.org[Apache Maven] with a plugin for https://www.axway.com[Axway] API Gateway.

The vision of the project is also to support a "marketplace" (Maven repository) of shared policies. Shared policies can be used by other projects just by adding the dependency to the project description. Everything else is handled by the plugin.

[NOTE]

The plugin focuses on policy development and API Gateway configuration. Promotion of APIs, as in the context of API Management, is not in scope of this project. If you are looking for automatic API promotion, please checkout https://github.com/Axway-API-Management-Plus/apim-cli[APIM CLI].

== Principles and Goals

. The truth is in the source code management (SCM). . Every development starts at the source code of the SCM. . The outcome of a project is a versioned artifact. . An artifact contains all required resources. . Versioned artifacts are immutable (except SNAPSHOT versions). . Dependencies between artifacts are managed by Maven pom.xml files. . Artifacts are stored in Maven repositories. . Support automatic build and configuration (DevOps support). . Configuration issues shall be detected at build time. . Easy team development without copy & paste or fragment import.

== Project Types

The plugin supports three kind of API Gateway projects:

[cols="1,<2a,3", options="header"] |=== |Project Type |Generated Artifact |Description

|Policy Project |Policy Archive

• policy directory (as generated by PolicyStudio)
• static files |Shared and reusable policies. No sever settings are included in the project. Policy projects may depend on other policy projects or external libraries (JARs).

|Server Project |Server Archive

• .pol file
• .env file
• static files
• external libraries (JARs) |Policies including server settings. Server projects may depend on other policy projects or external libraries (JARs). Server projects are environment independent.

|Deployment Project |Deployment Archive

• .fed file (environment specific)
• static files
• external libraries (JARs) |Configures the environment independent server projects for a specific environment or group. A deployment project depends on exactly one server project. |===

== Features

• Manage dependencies via Maven pom.xml
• Initialize policy and server projects with default factory templates.
• Start PolicyStudio via Maven goal Project dependencies of PolicyStudio are configured from pom.xml file. "Recent Projects" of PolicyStudio is initialized to open current project. ** Each project has a separate PolicyStudio configuration (running multiple PolicyStudio instances is supported).
• Configure environmentalized fields via JSON configuration.
• Support of separate property file for credentials.
• Check for unconfigured environmentalize fields (build fails in case of unconfigured fields).
• Add or replace certificates by alias via JSON configuration.
• Check of certificate expiration.
• Deploy projects to gateway via plugin.

== Installation

=== Build & Install

[source,shell]

git clone https://github.com/Axway-API-Management-Plus/apigw-maven-plugin.git cd apigw-maven-plugin mvn clean install

=== Download & Install

To download and install the plugin you could use the following script:

.install-apigw-maven-plugin.sh [source,shell,subs="verbatim,attributes"]

!/bin/bash

set -euo pipefail

APIGW_MVN_PLUGIN_VER={mvn-plugin-ver}

APIGW_MVN_PLUGIN="apigw-maven-plugin-${APIGW_MVN_PLUGIN_VER}" APIGW_MVN_PLUGIN_JAR="${APIGW_MVN_PLUGIN}.jar" APIGW_MVN_PLUGIN_POM="${APIGW_MVN_PLUGIN}.pom"

GITHUB_RELEASES="https://github.com/Axway-API-Management-Plus/apigw-maven-plugin/releases/download/v${APIGW_MVN_PLUGIN_VER}"

Download artifacts

wget -nv "${GITHUB_RELEASES}/${APIGW_MVN_PLUGIN_JAR}" -O "${APIGW_MVN_PLUGIN_JAR}" wget -nv "${GITHUB_RELEASES}/${APIGW_MVN_PLUGIN_POM}" -O "${APIGW_MVN_PLUGIN_POM}"

Install plugin

mvn install:install-file -Dfile="${APIGW_MVN_PLUGIN_JAR}" -DpomFile="${APIGW_MVN_PLUGIN_POM}"

== More to Read

• link:doc/getting-started/getting-started.adoc[Getting Started]
• link:doc/manual/user-guide.adoc[User Guide]
• link:doc/manual/_faq.adoc[FAQ]
• link:example/config-tool/README.adoc[Example for using standalone configuration tool]

== Known Limitations

• Documentation is not complete.
• Automatic adding of dependent JARs to PolicyStudio is currently not supported (on the road map).
• Environmentalized fields containing references are not supported.
• Unconfigured envSettings are not detected.

== Contributing Please read https://github.com/Axway-API-Management-Plus/Common/blob/master/Contributing.md[Contributing] for details on our code of conduct, and the process for submitting pull requests to us.

== Team image:https://raw.githubusercontent.com/Axway-API-Management-Plus/Common/master/img/AxwayLogoSmall.png[Axway Logo] Axway Team

== License link:./LICENSE[Apache License 2.0]