Skip to content
This repository has been archived by the owner on Aug 11, 2022. It is now read-only.

Home

Jump to bottom
Chris Wiechmann edited this page Apr 29, 2020 · 42 revisions

What is does

Swagger-Promote as a API-Manager CLI can either be used by the API-Service provider directly to replicate an API and it also helps to simplify the DevOps experience when using Axway API-Manager Version 7.x. It basically provides the ability to declare a "desired" API state, which will be replicated into the API-Manager to become the actual API state.

To achieve this the program compares the desired- with the actual-state and performs all necessary actions, using the API-Manager REST-API, to replicate the desired state into the API-Manager. This includes:

  • API-Lifecycle changes (publishing, deprecating, retirement)
  • API-Configuration, such as Security, Custom-Policies, Tags, c.
  • Application-Management
  • Quota-Management
  • and more

The desired state is declared using a configuration file and the API-Definition (Swagger/WSDL) itself. You can use api-import CLI to replicate that state into the API-Manager.
Optionally you can use the api-export CLI to generate the required configuration file based on existing APIs already configured in API-Manager.

If you would like to integrate Swagger-Promote into a pipeline for instance based on Jenkins read more here: Jenkins Integration with GitHub & Bitbucket

If something goes wrong, the tool automatically rolls back all changes it made so far to leave the API-Manager instance in a clean state.

Improve the API-Developer UX

The ultimate goal is to improve the API-Developer User-Experience, as it simplifies it's work massively no matter if using as CLI, as part of a pipeline or both.
The following describes how the process for the API-Service provider is, once the Swagger-Promote has been integrated into a CI/CD-Pipeline the workflow for the API-Developer will be like this:

  1. API-Developer generates / creates the API-Swagger-Definition
  2. Additionally he maintains the API-Control to control API-Security, used Tags, Custom-Properties, ...
  3. When he commits his desired state into version-control it's realized by the CI/CD pipeline and replicated into API-Manager. Learn more how to setup your pipeline.
  4. API-Developer can go to API-Manager, see his API, can subscribe to it, test it
  5. now he can do changes in the Swagger-File or API-Contract, once checked in, changes are replicated again
  6. existing API-Subscription incl. API-Keys, Credentials, etc. will stay
  7. API-Developer can continue testing without the need to re-subscribe
  8. If the API is ready for the upstream environment: API-Developer provides optional staging information (for instance to declare different API-Security in Prod than in Integration)
  9. Once committed, a dedicated CI/CD workflow can promote it to the Upstream environments (e.g. with special permissions)

API-Design-Phase

When an API is initially created/designed for the first time, it is common to have frequent changes to the API, until the API satisfies all needs from different personas. In that phase, API-Designers/API-Developers might have the need to Publish an API, right from the Designer into the API-Management platform without the need to leverage a CI/CD-Pipeline already. Just push, what you have to get feedback or test the API you designed.
This becomes possible with our API-Design partner Stoplight. Learn more.

More information

The following documentation will help you to understand how to effectively use this project.

How to get started - Learn where to get Swagger-Promote and how to use it

Control API-Configuration - How to setup the API in API-Manager with the API-Configuration file

Swagger or WSDL File - Some details how the API-Definition as Swagger- or WSDL-File is handled

Staging-Concept - APIs should behave differently between QA & PROD. This is explained here

Control environments - Make use of Environment-Files to control configuration of different stages/environments.

Integrate with Jenkins - Use Jenkins in combination with Bitbucket/GitHub to automate your pipeline.

Additional information some additional information. How to debug, some kind of roadmap, Integration with Stoplight

Generate reports of your API-Manager registry - For instance understand which Custom-Policies are used by which APIs.

☝️ Swagger-Promote has been discontinued and is replaced by the new APIM-CLI

Clone this wiki locally