connecting-systems-services-integration-suite-codejam

Exercise 06 - Expose integration flow via API Management

In this exercise, we will expose our integration flow via API Management and take advantage of the functionality provided by API Management to govern and monitor the calls made to the integration flow. Once the API is created we will expose it via the Business Accelerator Hub Enterprise (Developer Portal).

To achieve the above we create an API in API Management that will act as a proxy to our integration flow and we will leverage an OpenAPI specification to create it.

Under the assets/api-management folder you can find exports of the API that we will develop in this exercise at different stages, e.g. Before applying policies, after including the BTP connectivity policy and after adding the verify API Key policy. These files can be imported in your tenant in case you don’t have time to complete the exercise. To import them, go to Design > APIs > APIs > Import API button.

What is an OpenAPI specification?

From the specification website…

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.

In simple terms, the specification is a document that describes an API.

Why is it important? The OpenAPI specification is an industry-standard, it is widely adopted by different vendors/services to document their APIs and there is a huge community behind it. SAP has adopted the OpenAPI spec to document its APIs, e.g. in the SAP Business Accelerator Hub you can find the OpenAPI spec for the APIs exposed by the different products. If you download the JSON file listed within the SAP S/4HANA Cloud Business Partner API (API resources > API specification > JSON) and inspect it, you’ll notice that it follows the OpenAPI spec 3.0.0. Also, various SAP products, e.g. SAP Process Automation, API Management, Cloud Integration, SAP Data Intelligence, use OpenAPI spec to define/consume APIs.

Business Partner API - specification

🚨🚨 As part of the prerequisites of this CodeJam, you should have set up the API Management capability of SAP Integration Suite. If you’ve not done this, now would be a good time as we will start using API Management. 🚨🚨

Create API by importing OpenAPI specification

An OpenAPI specification for our integration flow is included in the assets of this CodeJam - integration-flow-openapi-spec-1.0.0.json. The spec describes the endpoint we are exposing in SAP Cloud Integration and the data structure of the request and response expected from our endpoint.

In case you wonder how the OpenAPI spec included in the assets was created…. The file was generated from a Postman collection, with the help of the postman-to-openapi CLI. The output of the utility isn’t the file that’s in the repo but it was great starting point to define the API specification.

👉 Open the specification file located under the assets folder in the root of the repository, e.g. connecting-systems-services-integration-suite-codejam/assets/cloud-integration/integration-flow-openapi-spec-1.0.0.json and update the following components.

.servers.url: Replace the value https://your-tenant-free-tier-gfm1c35e.it-cpi018-rt.cfapps.eu10-654.hana.ondemand.com with the value you configured for host variable in the Postman environment that communicates with the integration flow.
(Optional) .paths: Depending on how you are deploying your integration flows, you might need to update the path as well, e.g. from /http/request-employee-dependants-ex4 to /http/request-employee-dependants if you are not adding the suffix to the integration flows created.

Once we’ve updated the specification file, we can use this to create an API in API Management. Once the API is created we will add it to the Developer Portal. First, let’s go ahead and create the API.

👉 Navigate to the Develop > APIs component of SAP Integration Suite and click the Import API button. Select the recently modified OpenAPI spec and create a version for the API, e.g. v1. Check that everything is fine after importing the file and click the Save button. Once saved, you can Deploy the API.

Import OpenAPI specification to create API

To expose the API in the Developer Portal (Business Accelerator Hub Enterprise) we first need to add it to a Product and include the API within it. Let’s go ahead, create the product and publish it.

👉 In the Develop > APIs component of SAP Integration Suite, click the Create button in the Products tab. Enter a name and a title, e.g. Business Partners and include the Request_Employee_Dependants_v1 API. Lastly, click the Publish button.

For a detailed step by step instruction on creating a Product, checkout steps 2 - 7 of the Add an API Proxy to a Product tutorial.

After publishing the product, we can navigate to the Business Accelerator Hub Enterprise and see the Business Partners product we just published and the Request_Employee_Dependants_v1 API.

Business Accelerator Hub Enterprise - Business Partners product

Business Accelerator Hub Enterprise - Business Partners product

Send a message to the integration flow via API Management

Now that we’ve created the Request_Employee_Dependants_v1 API, we can communicate with our integration flow through API Management.

From the API Management UI

👉 Go to the API and “try out” the API from the Resources tab.

Import OpenAPI specification to create API

⚠️ The response is an HTTP 401. Why do you think we get that error? Are we missing something in our request? ❓❓
<summary>Hint 🔦</summary>
A Bearer token. The same that we send when communicating directly with Cloud Integration.
From Postman

👉 Update the proxy_url variable in the API Management Postman environment with the API Proxy URL that’s in the API and send a message to the integration flow by using the api-management > Request Employee Dependants Proxy request in Postman.

API Proxy URL

👀 In the gif below, you’ll notice that you need to specify a Bearer Token in the Authorization tab of the request. This is because we are not managing the authentication process with Cloud Integration in API Management. We will alter this behaviour in the next section.

Send message via API Management from Postman

At the moment we’ve set up an API (Request_Employee_Dependants_v1) in API Management that is a proxy for our integration flow. By doing this we can use API Management to add common API functionality to our API, e.g. secure the API, modify headers, transform message formats, or implement rate limits.

🧭 We’ve sent several messages to our integration flow via API Management. Take some time to check the message in Cloud Integration and explore the monitoring capabilities available to us in API Management (Monitor > APIs, Analyze section). You should see the successful and failed requests here. There is quite some information available to us here that can’t be easily visualised in Cloud Integration and API Management gives us.

API Management - Analyse section

Examples of policies that we can apply to the Request_Employee_Dependants_v1 API

Additional functionality can be set in API Management in the form of Policies. A policy is a program that executes a specific function at runtime, which is what allows us to add the extra functionality to our API.

To communicate with the integration flow we need to send a Bearer token in the request headers. This Bearer token is obtained by first authenticating against the token server using the clientid and clientsecret we got from the Cloud Integration runtime service key that was created as part of the CodeJam prerequisites.

Although it is possible to create a service key and share the details with a new consumer of the service, this approach might not be ideal as an administrator will need to be involved whenever new/update credentials is required. It is not self-service, meaning we cannot use the Business Accelerator Hub Enterpise to manage our application/credentials.

Given that the communication to our integration flow can now go through API Management, we can use API Management to change how we keep our service secure. In our case, we will apply the following policies:

Business Technology Platform connectivity: This policy template helps us communicate with APIs hosted on SAP BTP and that are protected by the BTP OAuth, e.g. our integration flow. The template will be used to authenticate against Cloud Integration using our existing service key.
Verify API Key: Creating an application in the Developer Portal will generate for us an Application Key. We can use this Application Key to authenticate our calls to a Product API in API Management.

To learn more about SAP API Management and how you can use policies in API proxies, check out the Managing APIs in your landscape with SAP API Management CodeJam.

Summary

You’ve made it to the last exercise of this CodeJam. Congratulations!!! 🎉 🙌. This is no easy feat as there is a lot to read/learn/process in the CodeJam and you need to dedicate some solid focus time to go through the exercises. Great job 👏👏👏!

We’ve achieved a lot in this exercise. We learnt about OpenAPI specifications, and how we can use a spec to create an API in API Management.