Manage your apiman instances from the command line.
Script actions, such as adding APIs and gateways, or display information about a running apiman environment.
Let's assume you have an apiman server running on http://localhost:8080
Step 1: Create a new API:
$ ./apiman manager api create \
--name example \
--endpoint http://example.com \
--initialVersion 1.0 \
--public \
--orgName test
Step 2: Publish it:
$ ./apiman manager api publish \
--name example \
--version 1.0 \
--orgName test
You're done! Hit your new API at: http://localhost:8080/apiman-gateway/test/example/1.0
You can also manage your apiman server.
Add a gateway:
$ ./apiman manager gateway create \
--name test-gw \
--endpoint http://localhost:1234 \
--username apimanager \
--password "apiman123!" \
--type REST
Add a plugin:
$ ./apiman manager plugin add \
--groupId io.apiman.plugins \
--artifactId apiman-plugins-test-policy \
--version 1.4.3.Final
You can do much more - see the Usage section.
Whilst running commands to control your apiman environment from the CLI can be helpful, sometimes you need to keep your configuration in a file that you can check into your source control system.
For this, apiman-cli has Declarative Mode.
Here's how it works:
Here's a simple YAML file (you can use JSON if you want):
# simple.yml
---
org:
name: "test"
description: "Test organisation"
apis:
- name: "example"
description: "Example API"
version: "1.0"
published: true
config:
endpoint: "http://example.com"
endpointType: "rest"
public: true
gateway: "TheGateway"
policies:
- name: "CachingPolicy"
config:
ttl: 60
definition:
file: "/home/user/swagger/example.json"
type: "application/json"
$ ./apiman manager apply -f simple.yml
INFO Loaded declaration: examples/declarative/simple.yml
INFO Adding org: test
INFO Adding API: example
INFO Configuring API: example
INFO Setting definition for API: example
INFO Adding policy 'CachingPolicy' to API: example
INFO Publishing API: example
INFO Applied declaration
The following things just happened:
- an organisation named
testwas created, - an API named
examplewas added with the endpointhttp://example.com, - a swagger definition was uploaded for the API in json format
- a caching policy was added to the API and configured with a TTL of 60 seconds and, finally,
- the API was published to the gateway.
Declarations also allow you to add gateways, install plugins and more. See the examples directory.
You can also use placeholders in your declaration files. This helps you reuse declaration files across different environments. For example:
endpoint: "${myApiEndpoint}"
...then pass them in when you run the apply command:
./apiman manager apply -f simple.yml -P myApiEndpoint=http://example.com
Additionally, you can specify a properties files, containing key-value pairs, such as:
./apiman manager apply -f simple.yml --propertiesFile /path/to/placeholder.properties
To avoid repeating the same policy definitions, you can define them once in the shared section of your declaration file, then refer to them by name later.
For example, see the shared-policies.yml file.
The same goes for properties - you can define them in the shared section and reuse them.
See the shared-properties.yml example file.
You can ensure all APIs in an organisation have a particular set of policies using the org/common/policies block.
Policies from the common block will be appended/prepended to the list of policies on each API in the organisation. Use the first and last lists to choose where to add the common policies in the policy chain.
org:
name: "test"
description: "Test organisation"
# Configuration and policies in the common org section are applied to each API.
common:
# Common policies are injected at either the start or the end of the policy chain for each API.
policies:
first:
- "alwaysFirstPolicy"
last:
- "alwaysLastPolicy"
apis:
- name: "example"
description: "Example API"
version: "1.0"
published: true
config:
endpoint: "http://example.com"
endpointType: "rest"
public: true
gateway: "test-gw"
# policies from the common block will be appended/prepended to this list
policies: []
See [examples/declarative/common-api-config.yaml] for an example.
You can ensure all APIs in an organisation have particular configuration using the org/common/config block:
org:
name: "test"
description: "Test organisation"
# Configuration and policies in the common org section are applied to each API.
common:
# Common configuration is overridden by API specific values.
config:
endpointType: "rest"
public: true
gateway: "test-gw"
apis:
- name: "example"
description: "Example API"
version: "1.0"
published: true
config:
endpoint: "http://example.com"
policies:
# ... policies go here
See [examples/declarative/common-api-config.yaml] for an example.
- An instance of apiman
- JDK 8
- OS X, Windows, Linux
The CLI lets you control both the apiman Manager and apiman Gateway components.
Typically, you will administer the Manager, then publish your changes to the Gateway (as per the UI flow).
apiman manager plugin [args...]
apiman manager org [args...]
apiman manager api [args...]
apiman manager gateway [args...]
apiman manager apply [args...]
--debug : Log at DEBUG level (default: false)
--help (-h) : Display usage only (default: false)
--server (-s) VAL : Management API server address (default:
http://localhost:8080/apiman)
--serverPassword (-sp) VAL : Management API server password (default:
admin123!)
--serverUsername (-su) VAL : Management API server username (default: apiman)
apiman manager org show [args...]
apiman manager org create [args...]
apiman manager org show [args...]
--name (-n) VAL : Name
apiman manager org create [args...]
--description (-d) VAL : Description
--name (-n) VAL : Name
apiman manager gateway test [args...]
apiman manager gateway show [args...]
apiman manager gateway create [args...]
apiman manager gateway list [args...]
apiman manager gateway list [args...]
apiman manager gateway create [args...]
--description (-d) VAL : Description
--endpoint (-e) VAL : Endpoint
--name (-n) VAL : Name
--password (-p) VAL : Password
--type (-t) [REST | SOAP] : type (default: REST)
--username (-u) VAL : Username
apiman manager gateway show [args...]
--name (-n) VAL : Name
apiman manager gateway test [args...]
--description (-d) VAL : Description
--endpoint (-e) VAL : Endpoint
--name (-n) VAL : Name
--password (-p) VAL : Password
--type (-t) [REST | SOAP] : type (default: REST)
--username (-u) VAL : Username
apiman manager plugin show [args...]
apiman manager plugin add [args...]
apiman manager plugin list [args...]
apiman manager plugin show [args...]
--debug : Log at DEBUG level (default: false)
--help (-h) : Display usage only (default: false)
--id (-i) VAL : Plugin ID
apiman manager plugin add [args...]
--artifactId (-a) VAL : Artifact ID
--classifier (-c) VAL : Classifier
--groupId (-g) VAL : Group ID
--version (-v) VAL : Version
apiman manager plugin list [args...]
apiman manager api create [args...]
apiman manager api list [args...]
apiman manager api publish [args...]
apiman manager api create [args...]
--endpoint (-e) VAL : Endpoint
--endpointType (-t) VAL : Endpoint type (default: rest)
--gateway (-g) VAL : Gateway (default: TheGateway)
--initialVersion (-v) VAL : Initial version
--name (-n) VAL : API name
--orgName (-o) VAL : Organisation name
--public (-p) : Public API
--serverVersion (-sv) [v11x | v12x] : Management API server version (default:
v11x)
apiman manager api list [args...]
--orgName (-o) VAL : Organisation name
--serverVersion (-sv) [v11x | v12x] : Management API server version (default:
v11x)
apiman manager api publish [args...]
--version (-v) VAL : API version
--name (-n) VAL : API name
--orgName (-o) VAL : Organisation name
--serverVersion (-sv) [v11x | v12x] : Management API server version (default:
v11x)
A 'declaration' is a configuration file specifying Gateways, APIs and policies. See the Declarative API management section for more information.
apiman manager apply [args...]
--declarationFile (-f) PATH : Declaration file
-P VAL : Set property (key=value)
The following commands are available, when administering the Gateway directly:
apiman gateway generate: Generate configurations
apiman gateway apply: Apply Apiman Gateway declaration
apiman gateway org: List Organizations
apiman gateway api: Retire and list APIs
apiman gateway client: Retire and list Clients
apiman gateway status: View Gateway Status
--debug: Log at DEBUG level
--help, -h: Display usage only
When working with declaration files, in any of the following scenarios:
- declarative gateway
- declarative manager
- generate headless gateway configuration
...the commands support repetition of the --declarationFile argument.
This means you can do things like:
./apiman manager apply --declarationFile=/path/to/file1.yml --declarationFile=/path/to/file2.yml
...and the declarations will be merged in the order the files are provided.
For recent changes see the Changelog.
See the Roadmap document for future plans.
If you just want to run apiman-cli, use the apiman or apiman.bat (Windows) scripts in the root directory.
If you want to compile the JAR yourself, use:
./gradlew clean shadowJar
Note: for distribution, apiman-cli is built as a 'fat JAR' (aka 'shadow JAR').
...and look under the build/libs directory.
Importing into your favourite IDE is easy, as long as it supports Gradle projects.
If you want to run unit tests, run:
./gradlew clean test
If you want to run integration tests, ensure you have an apiman instance running on http://localhost:8080, then run:
./gradlew clean test -PintegrationTest
Pull requests are welcome.
Pete Cornish ([email protected])