- SAP Managed Tags:
As you may know, API-centric approaches are becoming increasingly popular in the integration world.
As a result, API Management, a capability of SAP Integration Suite, is slowly but surely gaining more and more attention.
In this article, I'd like to show you the process of creating and exposing a basic API in API Management, as well as some of the technical possibilities, such as dynamic routing and policies.
In this example, we'll expose the free and open source API https://moneymorph.dev using our own custom API.
A special thanks goes to Mads Voldby Obel for giving me permission to use his project in this blog.
MoneyMorph currently has a total of 3 endpoint - latest, currencies & convert. Our goal is to expose all of them using API Management.
The endpoints are:
Latest - https://moneymorph.dev/api/latest
Currencies - https://moneymorph.dev/api/currencies
Convert - https://www.moneymorph.dev/api/convert/{amount}/{from}/{to}
Let's get started!
1.1 Preprequisite - API Provider
Under Configure -> APIs -> API Providers we create our very own API provider called Provider-for-Currency.
For host we enter moneymorph.dev, port is 443 and checking the SSL box as well.
1.2 Prerequisite - API Proxy
Next is creating our own API proxy. To do so, choose Configure -> APIs -> API Proxies and press the create button. Remember to select our previously created API provider.
Now that we have our provider & proxy, we can begin to look into the resources.
2.1 Resource - "Latest"
In the next step, we begin to create a resource to display the latest functionality.
And basically, that's already it! Why? Firstly, we don't need to handle Authentication when dealing with MoneyMorph. Also, when we created our API, the base-URL we're pointing to is https://www.moneymorph.dev/api. The path prefix of our resource is "/latest". When calling the resource of our API, the path prefix is automatically added to the base-path of the API.
Can you already spot the problem? 🙂
We can check the result of the API call using the API test console. But first, remember to save & deploy the API. When we go to our API test console and select our API, our "latest" resource is already pre-selected.
Clicking on "Send", you will be able to see the proper response from MoneyMorph now.
The problem I teased above becomes quite clear when you remove the "/latest" at the end of the URL in the test cockpit and replace it with "/currencies". Now once again click on the send button.
You'll notice that the call was successful and instead of the previous result, you get a list of the available currencies. Why is that?
Its because of the default routing rules which was automatically created when we created our API.
Navigate back to our Currency-API and select Proxy EndPoint.
At the bottom you see the Route Rules in place. In the beginning, there is only the default route rule which points towards the Target End Point default and doesn't contain any condition at all. Therefore, all calls to our API are routed to the Target End Point "default".
When you select "Target EndPoint" right next to Proxy EndPoint, you can see the default endpoint.
It points exactly to the URL we provided when creating the API.
In order to for us to limit our default target EndPoint to the latest resource, we remove the default route and add our own. As a condition, we set proxy.pathsuffix MatchesPath "/latest". And because the naming of target endpoint "default" isn't that great, we remove it and instead create a new target Endpoint we call latest-endpoint. The URL will be the same of course.
If you're wondering how to build a condition on your own or ask yourself what other options there are, please check out this official SAP resource. I found it incredibly helpful.
Now our Proxy EndPoint and Target EndPoint should look like this:
Now we can go back to our API Test Console and check once more (don't forget to save & deploy before). Calling the latest endpoint still works fine, but removing /latest at the end of the URL and replacing it with /currencies causes an error.
2.2 Resource - "Currencies"
Let us look at the next MoneyMorph resource we can use in our API - Currencies. However, this time we will not simply name our resource "currencies" and basically route it through 1:1 as we did with "latest". This time, we will name our resource differently and find a way to make it work.
We create another resource named allCurrencies.
And of course we also need a new routing rule as well as a new target endpoint.
The target endpoints name is currencies-endpoint & the routing rules condition is proxy.pathsuffix MatchesPath "/allCurrencies".
The challenge we face is quite evident. Triggering this endpoint will call the URL moneymorph.dev/api/allCurrencies. Of course, that is not a valid resource. Therefore we need to find a way to call moneymorph.dev/api/currencies instead. Perhaps debugging the resource will give us an idea.
Go to the API test console, select our API and make sure to choose our new resource allCurrencies. Then click on the Debug button at the bottom right of the window. Click on Start Debug - also at the bottom right - and navigate back to the test console. Make a call towards our allCurrencies endpoint. Unsurpringly, we get an error saying "not found". Go back to the debug screen and click on Stop Debug.
Now you can see information about all steps the API call has taken. You can take your time and check out every single entry. I found it to be quite useful in the past to debug an API when I encountered a problem.
Pay particular attention to the very last entry, marked red in the screenshot below.
Here you are able to see the full URL which was called. But more importantly, you can actually see the variable containing the full URL being called.
Now we know that the variable target.url contains the URL which is called, we can think about manipulating this URL so it points to the correct resource.
One way to achieve this is by making use of policies. An overview over available policies can be found here.
For the sake of this example we're going to make use of the AssignMessage policy. Studying the documentation provided by SAP (here) reveals that it allows us to assign variables.
So lets use this policy to manipulate the target.url variable we found earlier so that it addresses the correct URL.
Go back to your API. Under the tab Target EndPoint, make sure to select our currencies-endpoint. Now click on the Policies button. Click on Edit and then choose Flows -> TargetEndPoint: currencies-endpoint -> PreFlow. Now you can add the Assign Message policy. Give it a name, e.g. currencies-URL, and choose add.
Click on Update to finish the policy and of course don't forget to save & deploy the API once more.
Head back to the API test console and try our allCurrencies endpoint one more time.
It works!
2.3 Resource - "Convert"
The last resource for us to create is convert. Looking at the MoneyMorph description of it, we need to provide 3 arguments in the URL for it to work. The amount, the currency its converted from and the currency its converted to.
You know the drill by now - go back to the API, create a new resource and then create a new routing rule & target endpoint. As for the routing rule, we need to take into consideration that URL params are passed along this time. Subsequently the rule might look like this:
The URL params needed to use the convert functionality are the hurdle for this resource. Luckily, SAP lets us use the API Designer!
Choose the option Edit in API Designer and you will be able to see the OpenAPI specification SAP automatically created for our resources so far.
SAP provides a documentation on how to add those parameters to a resource, see here.
Let's adapt the convert resource accordingly.
After saving, we can see how the resource changed. The URL params are expected now.
So at last, let's test it in the API test console.
And it works! As you can see, all 3 resources are functional now.
We've successfully built our API, making use of a policy, using routing rules, creating multiple endpoints and even using the API Designer in the end.
Surely there are even more ways to expose a resource, which further highlights the versatility of API management.
I hope these examples provided some insight and made you even more curious to explore API Management.
1 Comment
