Cloud Integration: OData API on API Business Hub
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.
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
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.
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.
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.