API Design API Management

Streamlining API and microservices workflow

API Design

Enterprises are adopting APIs, Cloud Services, and microservice-based architecture more than ever. And by that, the demand for API-based integration is overwhelming the enterprise IT. Quite often, they become a bottleneck for integration requirements from business departments that need to combine data and services from different providers, such as Cloud Applications, into new and innovative custom products.

To overcome this bottleneck and enable companies to be most innovative, Enterprise IT must allow businesses to do integration tasks on their own. The API Management solution must become a real platform: A self-service platform enabling business departments to provide and consume services easily. For that IT is providing the API Solution, along with processes and tools, still making sure APIs are secured, deployed in a controlled way, but not being responsible anymore for each individual API.

These tools and processes must support the whole API Lifecycle starting from API Design, quickly Mock-Up an API, control the API Usage in production and lastly a process to retire an API.

The primary goal of an enterprise API Management platform is to make internal and external services discoverable, by providing a centralized API Catalog. This enables business departments, for example, to find an existing integration in a cloud application and combine that data in their own projects. The same applies to services created by On-Premise Applications. Going this way enables a company to massively increase its own innovative strength.

But, you can only discover in the platform, what has been registered before. Hence, the Self-Service processes for API Service provided are super important for the success of the API Management platform.

API Design

Everything has a start and it makes even sense to register just your idea of something, so to say the API Design into the platform. This lets others know that you have started to work on something instead of waiting for the final API Implementation before registering it.

From that point in time, your brand-new API Idea is discoverable and may gain interest. And others may come to provide you with valuable feedback helping you to make your API better. And better can mean different facets, as illustrated by the API-Designed-Diamond by Arnaud Lauret in his book The Design of Web APIs.

Source: illustrated by Arnaud Lauret from his book: "The Design of Web APIs." This shows the API-Design-Diamond:
Source: illustrated by Arnaud Lauret from his book: “The Design of Web APIs.” This shows the API-Design-Diamond:

You as an API Developer are now hoping to get much valuable feedback, but the incorporation of this feedback into your API Design must be fast, easy, repeatable and, of course, without the help of enterprise IT. For you, as the developer doing other things as well, it must become a matter of simply changing your API Design, put it into version control and a platform process takes it from there. By magic, of course, using some kind of CI/CD-Pipeline, the API appears including the incorporated feedback in the enterprise API Catalog.

This is what I call the API-First approach. It must be an easy and repeatable process and you as the API Developer or API Product owner just use tools and processes provided the API Platform. No contact at all with enterprise IT to do that.

What’s next? Design an API using Stoplight.io!

One way to design an API is by using Stoplight.io. API Developers or API Product owners can create, mock, document and collaborate on APIs using a graphical design view. No need to be an Open API Specialist.

Everything your developers do in Stoplight.io goes into a Git Repository. With that, API Developers define the API as they want to have it: This becomes the desired API state.

This is automatically picked up by a CI/CD-Process which does everything needed to replicate this desired state into the API Management platform, to become the actual API state. Et voilà, the desired API appears in the corporate API Catalog.

Your API Developers don’t care about what’s happening in the background, but Enterprise IT can easily adjust this automated API deployment process about additional rules, such as Security Checks, perform integration tests or validate corporate compliance rules. This also helps to avoid that someone deploys breaking changes for an API.

Axway customers are using tools such as Swagger-Based promotion to set up this workflow.

I call all these “APIs as code,” similar to “Infrastructure as Code,” as the Version-Control-System becomes your single source of truth for your APIs and from there it controls all stages of your API Management platform no matter if on On-Prem/Cloud or QA, Pre-Prod, Prod. It becomes a matter of a deployment task!

Having that kind of processes in place you already made a major step towards success for your API Management platform.

API Mock-ups

Also, your Enterprise IT should provide an easy way to allow API Developers to quickly mock-up APIs. Mocking an API helps to decouple the API Implementation project from the API Consuming project and by that gain speed. Additionally, developers get better feedback on their APIs, as potential consumers can really call the API and see what’s happening. Creating a Mock must be simple for them as well, as the Mock Service lives only for a short period of time. And, of course, all this must be possible without interaction with Enterprise IT.

One way to do that is Axway API Builder using the API-First approach. API-Builder is a Node.js based low-code-no-code framework, that can be individually installed on API-Developer workstations using npm. Creating the required Mock-Service is a matter of minutes, by creating a new API-Builder project, register the API-Design and use the Mock-Feature. Once, the API Builder project is version-controlled it is also picked up by the prepared CI/CD-Process. A Docker-Image is automatically building and finally becomes a microservices that runs as a Docker container natively or on an orchestration platform, such as Kubernetes, OpenShift, etc.

The next logical step in the API Lifecycle is to create a real API-Implementation service. Depending on the use-case, it could be either an API-Builder project or any other business application providing the required API.


Consider your API Management solution as a platform, enabling business departments to do as many as possible on their own. We at Axway call this going from High Control to High Productivity. In High Control, highly specialized people are doing almost all integrations tasks, but the Productivity is low, as these people are limited and become a bottleneck. Instead, enable other people to do integration tasks to increase productivity. One step in that direction is the API Management Self-Service platform. This may be combined with other integration patterns later, such as MFT, B2B using a hybrid integration platform.

Don’t be disrupted! Learn more about how API and microservices are changing the way people think.