API Management as your unique API repository
SAP API Management is one of the most interesting service available on SAP Cloud Platform, it allows you to easily create, govern and monitor APIs and securely share your digital assets, processes, and information with developer communities. I’m assuming you are familiar with API Management, you’re not? I absolutely suggest to have a look to this service on your SAP Cloud Platform trial instance!
APIs, most of the times, are created from existing oData services in your SAP or non-SAP systems, but sometimes you already have applications (for example SaaS applications) that expose APIs and your challenge at this point is: “How can I easily govern all these API repositories?“.
You can easily understand that multiple API repositories complicate not only the governance of these resources (security, authentication, provisioning and so on…), but also confuse your developer communities that can’t easily find the right APIs jumping from one portal to another.
In these days, I played around on this scenario, SAP API Management as a central repository for all your APIs, and I want to share with you my experience that may be useful for many of you.
As you may already know, I look into this not only as an opportunity for your company to simplify your business, but also from an IT prospective ( I’m always a developer inside 🙂 ).
My wonderful Fortune 1,000,000,000 company (I know this is unreal, but please indulge my fantasy) is 100% API oriented, all our APIs are available via SAP API Management to our customers and suppliers and, in accordance with our expansion strategy, today we have deployed a new SaaS application that provides real time weather and forecast via API (OpenWeatherMap).
We are exactly in the situation described before, two API repositories and for the second one we have no control on the APIs, we just need to use as they are.
My great team of API designers was able to solve this problem with our SAP API Management on SAP Cloud Platform. Let me explain their implementation (to clarify my team is basically myself, I’m an ambitious startup).
1. Request API Key from OpenWeatherMap
First step is to request an API Key from the API server of the OpenWeatherMap, this will be used to authorize our calls.
So we connect to https://openweathermap.org/api and request a new API Key
once we receive our API Key we can test the weather API (http://api.openweathermap.org/data/2.5/weather?zip=60610,us&appid=<your_api_key>) to make sure that everything is ready to rock!
Yeah, we can call our API from OpenWeatherMap.
2. Create a new API Proxy on SAP Cloud Platform
Now we want to create a new API on our SAP Cloud Platform, so we can consolidate our API Repository into one single place.
Let’s connect to our Access API Portal and create a new API
We can save and deploy the new API and easily test it from our API Management.
3. Enhance our API design
Currently the API endpoint is hard-coded in our API Proxy and actually I really don’t like this, I want it to be dynamic and flexible.
Let’s go back to our API proxy definition and remove all the query parameters, we will inject in our API call.
We can test our service now using the following URL: https://<user>trial-trial.apim1.hanatrial.ondemand.com/<user>trial/CurrentWeather?zip=60610,us&appid=<api_key> and it’s a kind of magic… it works, but wait a second are we sharing our API Key with everyone? How we can control access and mitigate any Denial of Service attack?
Let’s the fun begin, we will implement some API policies!
Mask OpenWeatherMap API Key
First we want to mask our OpenWeaherMap API Key. Select the API Proxy and click on “Policies” and add in the TargetEndpoint Preflow (1) a new “Assign Message” policy (2) as an “Inbound Request Stream“.
Now we can add the appid into the query string of our request using the following XML code:
<!-- This policy can be used to create or modify the standard HTTP request and response messages --> <AssignMessage async="false" continueOnError="false" enabled="true" xmlns='http://www.sap.com/apimgmt'> <!-- Sets a new value to the existing parameter --> <Add> <QueryParams> <QueryParam name="appid">your_api_key</QueryParam> </QueryParams> </Add> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <AssignTo/> </AssignMessage>
We can update and save the proxy and test the service using the following URL https://<user>trial-trial.apim1.hanatrial.ondemand.com/<user>trial/CurrentWeather?zip=60610,us
Perfect it still works, but now we need to enable our developers to request and use an API Key and control the access to our API.
Control API using API Key
This is actually a common practice for any API that you create on your SAP API Management and it is well explained in this tutorial on the SAP Developers Portal.
Note: to simplify future test of the API, I used the APIKey as a queryparam instead of an header
<!--Specify in the APIKey element where to look for the variable containing the api key--> <VerifyAPIKey async='true' continueOnError='false' enabled='true' xmlns='http://www.sap.com/apimgmt'> <APIKey ref='request.queryparam.APIKey'/> </VerifyAPIKey>
If all the steps are correct you should the following message while testing your API
Great our API is secured from unknown callers, but how can we now obtain an API Key?
We need to create an API Product containing the API Proxy just created and publish it into the API Developer Portal.
This step is also a very common one. If you’ve already designed an API, you will be very familiar, if not there is a great tutorial to accomplish this task.
Here we go! Our API Product is available in our API Developer Portal
As a API Developer, we drill down in our product definition and we find our Weather API. Our next step is to subscribe for consuming this API.
In the bottom-right corner of this page there is a button “Subscribe“, that allows us to create a new application to consume this API Product.
We are almost done, open the Consume APIs menu and select our newly created Application and again let’s the magic happen we have our API Developer Application Key that allows us to consume the API.
There is one final step, if we call again the API OpenWeatherMap, it returns an error message saying that the API Key provided is incorrect, this is due to the design of the API on the destination system that allow to add the API Key either as appid or api_key. This is not a problem, we just need to remove our SAP Cloud Portal APIKey query parameter when we call the OpenWeatherMap API.
Let’s go back to our API policies in the API portal and modify the appid_OpenWeatherMap policy we created in the previous steps as below
<!-- This policy can be used to create or modify the standard HTTP request and response messages --> <AssignMessage async="false" continueOnError="false" enabled="true" xmlns='http://www.sap.com/apimgmt'> <!-- Sets a new value to the existing parameter --> <Add> <QueryParams> <QueryParam name="appid">your_api_key</QueryParam> </QueryParams> </Add> <Remove> <QueryParams> <QueryParam name="APIKey"/> </QueryParams> </Remove> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <AssignTo/> </AssignMessage>
and now success! We are good to go!
Conclusion and final challenge
We were able to consolidate our API Developer Portal including an API from another API Portal and secure it with an API Key provided by our SAP Developer Portal.
Great success! Our great startup is still on the edge of technology providing great APIs to all of our partners with an unified aPI Developer Portal on SAP Cloud Portal that can be monitored and governed easily!
I want to leave you with a final challenge, are you ready?
Let’s assume that our company doesn’t want to use the syntax zip=60610,us, but, for functional requirement, wants to use zip=60610&country=us. How would you achieve this?
The challenge in on, the first to respond correctly will have a contract as API designer in my startup (you know that it is a joke right? The startup doesn’t exist, but you’ll still win the competition)