The article will walkthrough how I used Azure API Management (APIM) to integrate a software as a service application (SaaS) with a dumb API.
A dumb API is an interface that is missing many characteristics that we expect these days. For example discoverability and adherence to commonly accepted architectural styles is missing. This API is hosted on-premise and returns a JSON payload. It is dumb because the documentation comes as a Excel file. Furthermore it uses a POST with a JSON payload to read data from the back end application. Integrating with interfaces that do not meet modern standards is common challenge that I face. That is why I have chosen to write about it here.
The SaaS application is modern and hosted in the cloud and has the following requirements;
-
-
-
- The SaaS application developers require an API definition e.g. Swagger.
- The Rest API should be protected with OAuth authentication.
-
-
The solution I have shown below uses APIM to provide the swagger documentation and security abstraction to the SaaS developers. The APIM endpoint will connect from Azure using a VPN to the on-premises dumb API.
An example of documentation that is in a spread sheet is shown below. This has to be converted to swagger documentation before it can be imported in to APIM. I have used Restlet studio to create Swagger files and I recommend it. This time I decided to try something different. Inspired by the Global Integration Bootcamp Lab #1, I decided to create a Web API stub. I will get the swagger from that. Furthermore this would also give my developers a test stub to work with.
The main task in building the Web API App was creating the models that represented the documented JSON request and response. Secondly the controller must be annotated for swagger as shown below.
Finally I ran the project in debug. I added /swagger/docs/v1 to the url to generate a swagger file. I saved the file so that can be imported into APIM later on. Note that if you just add /swagger to the URL you just get the swagger documentation pages.
Now we are ready to configure the API in APIM. Browse to the APIM blade and select APIs ( currently in Preview and select the OpenAPI specification.
Choose the upload option, browse to the swagger file you saved above and upload it. Finally press create to complete the configuration.
At this stage the swagger documentation can be displayed. The try it button will not work because the URL is pointing at the http:\\local. Use the tab at the top left hand corner of the blade to navigate to the publisher portal. Choose the products tab and choose your product. You should get to a product page like this;
Choose “ADD API TO PRODUCT” and select the new API. Ensure that it is published and that you have set up the subscription requests. Return to the API’s blade of APIM in the new portal and select Developer portal. Once the portal opens select the API and then the new API. The Swagger documentation displays as shown in the example below.
The first goal, documenting the dumb API has been achieved. Finally the correct endpoint to the dumb API must be configured.To test this I deployed my WebAPI stub and wired it up as shown in the diagram below. Eventually this will be replaced with the URL of the dumb API. This will be connected via a VPN from the same Azure subscription that the APIM is hosted.
In summary we have hosted a dumb APi in APIM and now we can use all its goodness to add authentication, logging, monitoring. The SaaS developers are now happy because they think they are connecting to a modern API but are they!
