Cloud Integration – Remote OData API’s for Integra...

former_member587030 · ‎2018 Jul 06

Introduction

There are many operations that can be performed on an Integration Flow like create, configure, deploy, etc. using the SAP Cloud Platform Integration’s Web Application. But now with the introduction of remote OData APIs, it is also possible to perform similar operations on the integration flows (also known as Integration Design time artifacts) remotely, using a REST client.

This blog will explain how to Configure and Deploy an Integration design time artifact along with the newly added feature mentioned below.
These API enhancements are further detailed in SAP Help Portal: Integration Content Designtime – OData API.
To try these out on API Business Hub, check out the blog : Cloud Integration: OData API on API Business Hub

New with SAP Cloud Platform Integration 4 August 2018 release:

New feature enhancements include APIs for enabling various operation like Get, Create, Update, Delete and Download of Resources in an Integration Flow.

New with SAP Cloud Platform Integration 7 September 2018 release:

New feature enhancements include APIs for enabling copy of Integration Package from Discover to Design

New with SAP Cloud Platform Integration 28 October 2018 release:

New feature enhancements include:

support for certain Query Parameters in API calls and

Improved version handling for remote api calls :

To get the design time artifact details or its resources or configurations, it is necessary to pass the bundle Id and the bundle version in the Odata call. In case the user is unaware of the version or if the artifact is updated to a newer version, the user will have to verify the bundle details in WebUI.

To overcome this problem, we have introduced a version constant called ‘active’, which always returns the latest artifact.

For example, while making the call to read the artifact ‘TestRemoteAPIRead’, the string ‘active’ can be used for for version.

The same verion can also be used to download or to fetch resources and configuration information.

Note – The text ‘active’ is not case-sensitve and can be used a in any case forms such as ‘Active’ or ‘ACTIVE’

Configure an Integration Flow

Configure operation allows you get all externalized parameters and also update a single parameter or multiple parameters in a single REST call.

Get Parameter Details

In order to fetch the details of all the parameters externalized in an integration design time artifact, execute the following steps.

The URL for configuring single parameter in one REST call is :

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<integrationFlowID>',Version='<version>')/Configurations

In the above link,

tmnurl represents the URL of the tenant where the integration flow exists

integrationFlowID denotes the id of the integration flow

version represents the latest active version of the integration flow

Note : integrationFlowID can be fetched by opening the integration flow in Web UI and checking the ID field, under General tab of the integration flow configuration.

These details must be replaced and updated in the URL.

Paste the above URL in any Rest Client of your choice (e.g. Postman)

Select HTTP GET

Select Send

Single Parameter Update

In order to update a single parameter value of an integration design time artifact, execute the following steps.

The URL for configuring single parameter in one REST call is :

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<integrationFlowID>',Version='<version>')/$links/Configurations(<parameterKey>)

In the above link,

tmnurl represents the URL of the tenant where the integration flow exists

integrationFlowID denotes the id of the integration flow

version represents the latest active version of the integration flow

parameterKey denotes the name of the parameter you wish to update.

These details must be replaced and updated in the URL.

Paste the above URL in any Rest Client of your choice (e.g. Postman)

Select HTTP PUT

Select Authorizationtab and provide the required authentication TYPE.

Select Headers tab and enter x-csrf-token key and its value.

Note : You can do GET operation on http header x-csrf-token : fetch to get the value of x-csrf-token.

In the Body tab, enter the request to update parameter value.

Below is an example of a request body of JSON format to update parameter value

Select Send.

Note: For updating a Scheduler or Timer parameter, the "ParameterValue" should be a valid cron expression and the "DataType" should be "custom:schedule". Please see the below example.

Multiple Parameter Update

In order to update multiple parameters of an integration design time artifact, execute the following steps.

The URL for configuring multiple parameters using Batch call is :

https://<tmnurl>/api/v1/$batch

In the above link,

tmnurl represents the URL of the tenant where the integration flow exists

These details must be replaced and updated in the URL.

Paste the above URL using any Rest Client of your choice (e.g. Postman)

Select HTTP PUT

Select Authorizationtab and provide the required authentication TYPE to login to the tenant.

Select Headerstab and enter the following header keys and their value:
- Set x-csrf-token.
- Set Content-Type as multipart/mixed; boundary=<batchboundry>.

Select Body tab and enter the batch request to update multiple parameter values.

Select Send.

Deploy Integration Flows

It is now possible to deploy an integration design time artifact via remote API call. To check how, execute the following steps.

The URL for deploying is :

https://<tmnurl>/api/v1/DeployIntegrationDesigntimeArtifact?Id='<integrationFlowID>'&Version='<version>’

In the above link,

tmnurl represents the URL of the tenant where the integration flow exists

integrationFlowID denotes the id of the integration flow

versionrepresents the latest active version of the integration flow

Paste the above URL using any Rest Client of your choice (e.g. Postman)

Select HTTP POST operation

Select Authorization tab and provide the required authentication TYPE to login to the tenant.

Select Headers tab and enter x-csrf-token key and its value.

Select Send.

Resource APIs

The following APIs allow you to manipulate resources in an Integration Flow.

Get All Resources

To fetch all the resources from an integration flow.

Provide the URL with Get Operation

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<integrationFlowID>',Version='<version>')/Resources

In the above link,

tmnurl represents the URL of the tenant where the integration flow exists

integrationFlowID denotes the id of the integration flow

version represents the latest active version of the integration flow

Update Authorization

Click on Send.

Get Resource

To fetch individual resources from an integration flow.

Provide the URL with Get Operation

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>',Version='<version>')/Resources(Name='<Resource Name>',ResourceType='<Type of Resource>')

In the above link,

tmnurl represents the URL of the tenant where the integration flow exists

integrationFlowID denotes the id of the integration flow

version represents the latest active version of the integration flow

Resource Name represents name of the resource with extension.

Type of Resource represents the type of the resource

Update Authorization

Click on Send.

Note: In a special case where XSD is referred by a WSDL and use case is read XSD from WSDL folder then user can customer query option.

https://<tmn>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>',Version='<version>')/Resources(Name='<Resource Name>',ResourceType='<Type of Resource')?ReferencedResourceType=< Type of Resource>

Create Resource

To create a resource in an integration flow.

Provide the URL with POST Operation

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>',Version='<Version>')/Resources

In the above link,

tmnurl represents the URL of the tenant where the integration flow exists

integrationFlowID denotes the id of the integration flow

version represents the latest active version of the integration flow

Provide CSRF Token (explained in the Integration Flow creation)

Update Basic Authorization

Provide JSON body content, as shown in the example below.

Click on Send.

Note: In a special case where XSD is referred by a WSDL and the use case is to put XSD in WSDL folder, the user can put additional attribute in payload.

Update Resource

To update a resource in an integration flow.

Provide the URL with PUT Operation

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>',Version='<version>')/$links/Resources(Name='<Resource Name>',ResourceType='< Type of Resource>')

In the above link,

tmnurl represents the URL of the tenant where the integration flow exists

integrationFlowID denotes the id of the integration flow

version represents the latest active version of the integration flow

Resource Name represents name of the resource with extension

Type of Resource represents the type of the resource

Provide CSRF Token (explained in the Integration Flow creation).

Update Basic Authorization.

Provide JSON body content, as shown in the example below.

Click on Send.

Note: In a special case where XSD is referred by a WSDL and the use case is to update XSD in WSDL folder, the user can use a custom query.

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>',Version='<version>')/$links/Resources(Name='<Resource Name>',ResourceType='<Type of Resource>') ?ReferencedResourceType=< Type of Resource>

Delete Resource

To delete a resource in an integration flow.

Provide the URL with DELETE Operation

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>',Version='<version>')/$links/Resources(Name='<ResourceName>',ResourceType='< Type of Resource>')

In the above link,

tmnurl represents the URL of the tenant where the integration flow exists

integrationFlowID denotes the id of the integration flow

version represents the latest active version of the integration flow

Resource Name represents name of the resource with extension

Type of Resource represents the type of the resource

Provide CSRF Token (explained in the Integration Flow creation).

Update Basic Authorization.

Click on Send.

Note: In a special case where XSD is referred by a WSDL and the use case is to delete XSD in WSDL folder, the user can use a custom query.

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>',Version='<version>')/$links/Resources(Name='<Resource Name>',ResourceType='<Type of Resource>') ?ReferencedResourceType=< Type of Resource>

Download Resource

To download a resource in an integration flow.

Provide the following URL with GET operation:

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>',Version='<version>')/Resources(Name='<Resource Name>',ResourceType='<Type of Resource>')/$value

In the above link,

tmnurl represents the URL of the tenant where the integration flow exists

integrationFlowID denotes the id of the integration flow

version represents the latest active version of the integration flow

Resource Name represents name of the resource with extension

Type of Resource represents the type of the resource

Update Basic Authorization.

Click on Send.

Note: In a special case where XSD is referred by a WSDL and the use case is to download XSD in WSDL folder, the user can use a custom query.

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>',Version='<version>')/Resources(Name='<Resource Name>',ResourceType='<Type of Resource>')/$value?ReferencedResourceType=< Type of Resource>

Count API

The Count API can be fired to get the number of resources and configurations for a given artifact. This can be done by firing a GET call with the following URL

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>’,Version='<Version>’)/Resources/$count

or

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>’,Version='<Version>’)/Configurations/$count

In the above link,

tmnurl represents the URL of the tenant where the integration flow exists

integrationFlowID denotes the id of the integration flow

version represents the latest active version of the integration flow

Update Authorization

Click on Send.

Query Options

The Odata API calls on Designtime artifacts will now support some of the system query options that are specified by Odata uri conventions. As Odata states - System Query Options are query string parameters a client may specify to control the amount and order of the data that an OData service returns for the resource identified by the URI.

Query options can be used along with others separated by ‘&’ to form a complex query.

The supported query options for the Designtime artifact calls are mentioned below.

Note- All Query Options for Odata calls begin with a ‘?’ character, after the respective URLs and name of each individual System Query Option is prefixed with a "$" character.

Orderby System Query Option ($orderby)

The order of the received data can be controlled by sorting it on one of the parameters or multiple parameters in ascending or descending orders.

Note- These queries can be performed on get resources and get configurations only

The below mentioned URL sorts the set of resources in an ascending order of Resources Names.

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>’,Version='<Version>’)/Resources?$orderby=Name

or

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>’,Version='<Version>’)/Resources?$orderby=Name asc

To sort it in the descending order the term ‘desc’ can be used instead of ‘asc’ as in

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>’,Version='<Version>’)/Resources?$orderby=Name desc

The below URL sorts the set of resources in ascending order of the resource types and the entries with the same resource types are sorted on their names.

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>’,Version='<Version>’)/Resources?$orderby=ResourceType,Name

The same action can be performed on Configurations call by the below URL

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>’,Version='<Version>’)/Configurations?$orderby=ParameterKey

Filter System Query Option ($filter)

The filter call will help fetch a subset of entries matching a given condition. The filter conditions supported by integration flows are ‘eq’ (equals) and ‘ne’ (not equals)

Note- These queries can be performed on get resources and get configurations only

For filtering resources on a condition on resource type

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>’,Version='<Version>’)/Resources?$filter=ResourceType eq 'groovy'

Or to avoid fetching a certain set of entries

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>’,Version='<Version>’)/Configurations?$filter=DataType ne 'xsd:boolean'

To help users encounter some uncertain conditions the remote API call also supports some of the string operations such as

·         Substring of - ?$filter=substringof('abc', Name) eq true

·         Startswith - ?$filter=startswith('scr', Name) eq true

·         Endswith - ?$filter=endswith(‘.groovy’, Name) eq true

Format System Query Option ($format)

The integration flow calls support the JSON and ATOM formats. By default the response is received in ATOM format. To receive the response in JSON format the mentioned query can be used

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>’,Version='<Version>’)/Configurations?$format=json

Note- This query can be performed on get resources and get configurations only

Select System Query Option ($select)

The properties returned in response can be controlled by using $select query. When used, only those properties are returned which are mentioned in the request.

Note – Select operation can be performed on get integration artifact, get resources and get configurations.

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>’,Version='<Version>’)/Resources?select=Id,Version

or

https://<tmnurl>/api/v1/IntegrationDesigntimeArtifacts(Id='<IntegrationFlowId>’,Version='<Version>’)/Resources?select=Name

Copy Integration Package from Discover to Design

In continuation of OData APIs offerings form SAP Cloud Platform Integration, with version 2.45.x, we have now enabled an OData API to copy an integration package from Discover space to Design space.

The URL pattern of the API is:https://<tmnurl>/api/v1/CopyIntegrationPackage?id='<id>'

In the above link,

tmnurl represents the URL of the tenant where the integration flow exists

id denotes integration package id. As of now, you can get this id from the URL of your browser’s address field as shown in the below screenshot (encircled)

2. When you perform the POST operation on the mentioned OData API, you shall get an HTTP 201 response code with response content as shown in the below screenshot which signifies the successful copy of integration flow package from Discover to Design space.

Also, below are the other supporting parameters of this OData API

https://<tmnurl>/api/v1/CopyIntegrationPackage?id='<id>'&ImportMode=’<import_mode>’

Values of the import_mode are

OVERWRITE : If you wish to overwrite the existing package which copying, you can provide this value, e.g. https://<tmnurl>/api/v1/CopyIntegrationPackage?id='<id>'&ImportMode='OVERWRITE'

CREATE_COPY : If you wish to create another copy of the same integration package while copying and it has to be followed by a suffix, e.g. https://<tmnurl>/api/v1/CopyPackage?id='<id>'&ImportMode='CREATE_COPY'&Suffix='123

Conclusion

These are the first set of remote OData API’s that are currently available and in the coming months, we will be releasing more API’s to allow download and delete of an integration flow from the design workspace. Hope this blog helps you in understanding these APIs and gives you enough information to get started with them. Feel free to give us your feedback !