Skip to content

FAQ

Jump to bottom
Chris Wiechmann edited this page Jun 4, 2020 · 7 revisions

What is the difference between apimanager-promote & swagger-promote?

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 Swagger Promote 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) Swagger-Promote can be used. And of course, the host must have access to the API-Manager.

How to do swagger promote for multiple APIs?

Swagger-Promote as the core component is not supposed to handle 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 Swagger-Promote for each API individually.

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

Yes, since version 1.6.3 this is possible. You need to provide the following details when calling Swagger-Promote:

-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, Swagger-Promote 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 trying to download the server-certificates, but the correct downstream host is finally configured in the Frontend-API.
Clone this wiki locally