Cloud Integration: OData API on API Business Hub

[sandra_voges]

Note that this blog will not be maintained any more. The blog Cloud Integration – Overview of OData API Documentation | SAP Blogs contains the current information about the OData API for Cloud Integration.

Introduction

The OData API of SAP Cloud Integration enables you to access the stored data (e.g. to implement a monitoring project) or to update data (e.g. to create/update/delete partner directory content). In the past these OData API entities were only described in SAP Help Portal (see SAP Help Portal: SAP Cloud Integration - OData API), but with SAP Cloud Integration 14-Apr-2018 release (v2.39.x) the first version of this API is published in the SAP API Business Hub.

New with SAP Cloud Integration 7 July 2018 release:
API package of SAP Cloud Integration is enhanced by access to "Design" section. These API enhancements are further detailed in  Blog: Cloud Integration – Remote OData API’s for Integration Flows and in SAP Help Portal: Integration Content Designtime - OData API.

New with SAP Cloud Integration 4 August 2018 release:
Integration Flow entity is added to "Integration Content" API.
The new API "Security Content" is provided with "Certifacte-to-User-Mapping" entity.

New with SAP Cloud Integration 27 October 2018 release:
Entity for discovering integration package is added to "Integration Content" API.
User credentials entity is added to "Security Content" API.


New with SAP Cloud Integration 24 November 2018 release:
ID mapper entity is added to "Message Processing Logs" API.

New with SAP Cloud Integration 19 January 2019 release:
Idempotent repository entity is added to "Message Processing Logs" API.


New with SAP Cloud Integration 16 March 2019 release:
Keystore entities are added to "Security Content" API.
Endpoints for runtime artifacts (deployed integration flows) are added to "Integration Content" API, which is described in more detail in Blog: SAP Cloud Integration – OData API for accessing the service endpoints.

New with SAP Cloud Integration 26 October 2019 release:
JMS resources entity is added to the renamed "Message Stores" API (old name: "Message Store").
OAuth2 client credentials entity is added to "Security Content" API.


New with SAP Cloud Integration 18 January 2020 release:
Integration package entity of designtime is added to "Integration Content" API.

API Package "SAP Cloud Integration"

This package contains the API list, which enables you to trigger the following actions:

• Integration Content
  Get the list of deployed integration artifacts.
  Deploy/undeploy integration artifacts.
  New with  7 July 2018 release: Get/deploy integration flow with configuration parameters of "Design" section.
  New with  7 July 2018 release: Update configuration parameters of integration flow in "Design" section.
  New with 4 August 2018 release:
  Download/delete integration flow of "Design" section.
  New with 27 October 2018 release:
  Copy package from "Discover" to "Design" section
  Create integration flow
  Support of 'active' version and query options for accessing integration flows in "Design" section
  New with 16 March 2019 release:
  Get all endpoints for runtime artifacts (deployed integration flows)
  New with 18 January 2020 release
  Create, read, change, delete integration packages in design section
  Get all/an integration flow(s) of an integration package in design section


• Log Files
  Get http and trace log files.


• Message Processing Log
  Get information about the message processing including error information, attachments etc.
  Get source/target ID from ID mapper (new with 24 November 2018 release).
  Get, delete idempotent repository entry (new with 19 January 2019 release).


• Message Stores
  Get the stored payload with payload attachments and header properties.
  Get JMS resources (new with 26 October 2019 release).


• Partner Directory
  Create, read, delete the Partner Directory content.


• Security Content (new with 4 August 2018 release😞
  Create, read, delete certificate-to-user-mappings.
  Create, read, change, delete user credentials (new with 27 October 2018 release).
  Generate, read, import, export, update, backup, restore, delete keystore entries including keystore renewal/history (new with 16 March 2019 release).
  Create, read, change, delete OAuth2 client credentials (new with 26 October 2019 release).

Image 1: API Package "SAP Cloud Integration" in SAP API Business Hub

"Try Out"

You have two different opportunities to test APIs directly in the API Business Hub. Either you use the API Sandbox or you configure an API environment for your tenant account. For both options you need to be logged on with your SAP Community User.

API Sandbox

It is possible to directly test the provided GET methods via API Sandbox (see SAP Help Portal: SAP API Business Hub- Trying Out PIs in Sandbox Environment), which is the default "Try out" feature.
The API Sandbox contains all test data for the provided APIs.

Example: GET All Deployed Integration Artifacts

Select the API, which you want to test.

Image 2: Select API

In "API References" select the required entity to get the corresponding method list.

Image 3: Open method list of an entity

Click on "Try out" of a "GET" method.

Image 4: Start test by clicking on "Try out"

Enter possibly required parameter values for the request and click on "Execute" button.

Image 5: Trigger request by clicking on "Execute" button

Afterwards you could see the received response directly underneath.

Image 6: Received response

Your Tenant Account

Alternatively to API Sandbox, you could test all methods (GET, POST, PUT and DELETE) in your SAP Business Technology Platform account by configuring API environment (see SAP Help Portal: SAP API Business Hub - Trying Out APIs in a Productive Environment).

For enabling tests with your account, click on "Configure Environments" for an opened API.

Image 7: Configure an API environment for "Integration Content" API

Select the region specific starting URL of your tenant account:



Image 8: Select region specific starting URL of your tenant account

Enter a display name, the account short name and the SSL host to complete the required URL for the API call and add your user credentials to complete the configuration.

The API environment contains the list of the display names for your configured environments plus Sandbox, which is selected by default. For test the API in your account you need to select the relevant environment display name before executing the method calls.

Image 9: Select display name of your account

As prerequisite for API test via your configured API environment your user needs to be assigned to the required roles (see SAP Help Portal: SAP Cloud Integration - Tasks and Required Roles).

CSRF Token Handling

For each write access a CSRF token is required. The corresponding fetch method “CSRF Token Handling” is part of each API with at least one write method.

To get the required CSRF token, at first the GET method needs to be called with the parameter X-CSRF-Token = Fetch.



Image 10: Fetch CSRF-Token

The received token must be copied from the response header.



Image 11: Copy CSRF-Token from response header

Afterwards this copied token needs to be entered into the X-CSRF-Token parameter of the POST, PUT or DELETE method.



Image12: Example: Paste the copied CSRF-Token into the corresponding X-CSRF-Token parameter field of DELETE IntegrationRuntimeArtifacts to undeploy an integration flow.

Look-Ahead

It is planned to further enhance the OData API of SAP Cloud Integration and to update this package in the SAP API Business Hub accordingly.
For example the API "Integration Content" will be further enhanced by new entity for designtime packages.

[Florian_Kube]

Thanks you Sandra for this blog entry.

I wonder how I am able to see the last processed messages. When I use the methode "Message Processing Logs" with the orderby option "LogStart,LogEnd desc" the order is still ascending.

[sandra_voges]

Hi Florian,

Thank you very much for this feedback!
The correct "$orderby" term should be "LogStart desc,LogEnd desc".
With the next update I will fix this issue of the GET method for the MessageProcessingLog artifact in the API package.

Thank you and best regards,
Sandra

 

[former_member327458]

Hi Sandra,

 

Thankyou for this wonderful blog. Its a great feature for the automation scenarios.

Is it also possible to get all the integration flow ids by passing the packageid?

 

[sandra_voges]

Hi Siby,

 

thank you very much for your feedback!
Currently the retrieval of artifact IDs for a given package ID is not supported by our API, but I will forward your feedback to the development.

Thanks and best regards,
Sandra

[former_member243807]

Hello Sandra,

We currently have many BAPI interfaces on ECC6 to maintain eg Sales Orders from external systems. The way it works is that a custom BAPI is called from the external system which formats the required data to feed and call the standard BAPI.

If we move to S/4 Hana (on-prem or cloud) what untimely gets executed in the backed SAP system? is it also a BAPI or somethig else ?

Thanks,

Peter.

 

[sandra_voges]

Hello Peter,

thanks for your feedback!

To be honest, I would assume that your question is independent of the described APIs, which are provided by SAP Cloud Platform Integration.

Possibly the following links could help to find an answer on your S/4 HANA specific question:

• Available BAPIs in S/4HANA Cloud for integration to SAP on Premise solutions (SAP Note 2447593)


• SAP S/4HANA Documentation

 

Thanks and best regards,
Sandra

[former_member632433]

Hi Sandra,

Thank you for the blog and also for consistently updating it. I was trying to implement this in our CPI tenant with API trial account.

Out of 6 Artifacts 4 artifacts are throwing the following error when I try to copy from Integration content. I was able to copy and perform API calls for the following artifacts

1. Log Files
2. Message Store

For the rest of 4 artifacts when I perform copy API I am getting the following exception. Could you please guide me?

Kind Regards

Ramesh

[sandra_voges]

Hi Ramesh,

thanks for your feedback!

It is interesting that the CPI API artifacts with only GET methods can be copied, but not those with POST/PUT/DELETE methods. I will clarify this with the colleagues from the API Management development team.

If this an urgent issue for you, please, create a ticket for the API Management component (OPU-API-OD-DT).

Thanks and best regards,
Sandra

[former_member632433]

Thanks Sandra for the quick response. We shall raise a note with SAP.

 

Kind Regards,

Ramesh

[sandra_voges]

Hi Ramesh,

the colleagues from API Management fixed this issue. It is now possible to copy all CPI APIs.

 

Thanks for reporting this issue and for helping to improve our tools!

Best regards,
Sandra

[vidyag]

Hi Sandra,

Thank you for the blog, it was really helpful. 🙂

I was wondering if there's any API to change the name of the iflow?

 

Thanks and Regards,

Vidya

[sandra_voges]

Hi Vidya,

thank you very much for your feedback!
Currently renaming an iflow is not supported by our API, but I will forward your feedback to the development.

Thanks and best regards,
Sandra

[nerevar]

Hello,

Is this kind of API also available for cloud foundry environments? is there a blog explaining how to do it?

thanks/regards

[kamlesh_zanje]

Hello Maxime,

Same set of APIs would work in CF/Multi-cloud environment as well.

You can refer the blogs that are highlighted in the introduction section of this blog or refer the documentation of API Business Hub -  https://api.sap.com/api/IntegrationContent/resource.

Regards,

Kamlesh.

[Clen]

Hi Sandra,

Great blog post!

I see using the OData API, we are able to download an integration flow of design time as zip file. Is there an API resource to download an integration flow as .MTAR file?

Kind regards,

Alexander

[kamlesh_zanje]

Hello Alexander,

We don't have public OData API to download integration flow as *.MTAR file.

Regards,

Kamlesh.

[Clen]

Hello Kamlesh,

Thank you for your answer.

 

Kind regards,

Alexander