FAQ - Axway-API-Management-Plus/apim-cli GitHub Wiki

Why should I use the APIM-CLI and not the API-Manager REST-API directly?

The API manager REST API is, as you probably know, designed to drive the API-Manager Web-UI and this basically controls the logic behind it. A consequence of this is that you would have to make n-API calls, for example to register an API, publish it, grant rights, manage quotas and subscribe applications.
The CLI aims to encapsulate the orchestration of these necessary API calls and to execute all necessary API calls to bring the desired state into the actual state.
It therefore simplifies the management of APIs and applications without having to worry about the internals.
It is planned to make some of the functions of the APIM-CLI exposed as REST-API.

What is the difference between apimanager-promote & the APIM-CLI?

The major difference is that the starting-point of your CI/CD-Pipeline: With apimanager-promote you need to use an API-Manager to manage your APIs, which is an additional overhead to API-Developers to do. They don't want to manage their APIs separately to make them compatible with the API-Manager. With Swagger-Promote an API-Developer can use any tool or framework (e.g. Code-Generators) that is able to produce a Swagger-File and connect his APIs directly with the API-Management platform.

The intention is to put your APIs under version control and by that you have something I call: APIs as Code similar to infrastructure as code. Perhaps review this slide-deck: https://www.slideshare.net/Axway/streamline-api-management

There are many reasons why it's better to start with the Swagger-File:

  • Deploy your APIs directly into the API-Management platform
    • you can repeat this over and over again, for instance on a change in your Swagger-File
      • adding new methods, parameters, etc.
      • Doing this by hand in API-Manager is a pain and error-prone
  • Staging your APIs becomes a matter you deployment
    • you can easily deploy your APIs into different environments, having different requirements
      • Security-Requirements, other Custom-Policies, etc.
  • the Swagger-File is a Standard-Format, the API-Export DAT-File is not
    • the API-Export Dat-File format is changing from API-Manager version to the next
      • as it is a kind of a Memory-Dump written to a JSON-File
      • as the internal data-structure is changing, the export-format is changing
    • this becomes important when you update your API-Manager and you can't import your existing API-Export files anymore
  • Swagger-Files and the API-Configs are simple JSON-Files
    • standardized formats
    • easy to read, easy to compare revisions, easy to rollback if needed, easy to audit
    • you can work collaborative on it using the Git-Flow (e.g. Pull-Requests, etc.)
    • existing tools can be made part of the CI/CD-Pipeline
      • e.g. validating the Swagger-File according corporate rule set
      • test your APIs with an existing test tool
      • etc.
    • there are many useful tools out there, but non of these will work with the Custom Export-Dat file

In one sentence I would say: With the APIM-CLI your CI/CD pipeline starts with the API (the Swagger-File + Config) itself and it can be registered directly & repeatable into the API-Management platform. This streamlines the API-Lifecycle dramatically.

Can I use it on Windows & Linux?

Yes, as long as the Operating-System provides a Java-Runtime (JAVA_HOME set) the CLI can be used. And of course, the host must have access to the API-Manager.

How to import multiple APIs?

The CLI doesn't support to import multiple APIs in one execution.

If you need to process multiple APIs, I recommend to write your own wrapper (e.g. Shell-Script), which may iterate over a directory/list/etc. and calls the CLI for each API individually.

Can I download the API-Definition from a Mutual-SSL protected URL?

Yes, this is possible. You need to provide the following details when calling the CLI:

-Djavax.net.ssl.keyStore=</path/to/keystore.jks>  
-Djavax.net.ssl.keyStorePassword=  
-Djavax.net.ssl.keyStoreType=

Error creating API-Proxy

When trying to register an API in API-Manager you may get the following error:
Response: 'HTTP/1.1 500 Internal Server Error'
Following with the error message:
Error creating API-Proxy. Unexpected response from API-Manager....
Most of the time this error is caused by the API-Manager when trying to import an API having an HTTPS downstream server. During registration the API-Manager tries to download the required certificates from the downstream server, hence the API-Manager needs to reach HTTPS-Host at registration time.
HTTPS-Post is not reachable
If the HTTPS-Host, given in the Swagger-File, can't be reached you get that error. For instance, the Swagger-File contains any Development-System not reachable from the production environment.
To workaround this problem do the following:

  • Use the configuration option: backendBasepath to define a valid host, that is reachable from that environment. Learn more
    With that, the CLI will adjust the Swagger-File before importing it into the API-Manager. Hence, the import should work.

When using a proxy for downstream communication
If your API-Management platform requires a proxy-connection to reach HTTPS-Downstream servers do the following:

  • define a plain downstream server in your Swagger-File (e.g. http://any.host.com). This might be even a non-existing host
  • set the option replaceHostInSwagger to false (to avoid the Swagger-File is adjusted before importing it)
  • set the parameter: backendBasepath to the valid HTTPS-Host
    With that, the API-Manager during import will no longer try to download the server-certificates, but the correct downstream host is finally configured in the Frontend-API. As the certificates are not downloaded anymore, they must be configured the API-Configuration file.

Are APIs updated with Zero-Downtime?

It depends on the configuration of the parameter: zeroDowntimeUpdate
If a published API can be updated without the need to re-import the backend API (e.g. changing a policy, tags, etc.), the frontend API is unpublished, changed and then republished.
This process only takes a few seconds, but technically leads to a short downtime for consumers. The advantage is that in this mode the API-ID and runtime quotas of applications are preserved. This is the NEW default behavior since version 1.3.0.

However, you can set the toggle zeroDowntimeUpdate to true to update APIs with zero downtime as before. That means that when updating a published API, the CLI always creates a completely new API (by Re-Importing the Backend-API, creating the Frontend-API), configures it according to the old API and finally clients are switched to the new API. This new API then has a new ID and runtime quotas are lost. The configured quotas are transferred to the new API.
See the file env.properties.sample how to set this parameter. It's also possible to give this parameter as a normal command line parameter.

How to configure the Load-Balancer when using the APIM-CLI?

Very likely your are running multiple API-Gateways/API-Managers behind a network Load-Balancer. It is strongly recommended, that the CLI communicates with ONE API-Manager instance. Therefore you should configure session stickiness based on an application generated cookie, as the CLI is not consuming new cookies that might be generated by the Load-Balancer. The application cookie name must be: APIMANAGERSESSION