SAP Cloud Integration – OData API for accessing the service endpoints

[kamlesh_zanje]

Introduction

SAP Cloud Integration 16 March 2019 release (v2.51.x/v3.9.x) is now enhanced with a feature available in the form of an Application programming interface (API) based on the OData V2 for accessing the service endpoints. OData API entities are described in the SAP Help Portal ( see Integration Content Entity Types and ServiceEndpoints Example Requests).

This blog describes how to consume this API.

New with SAP Cloud Integration February 2020 release (v3.21.x)

The OData API is now enhanced to support additional query parameters like $top, $skip to do pagination and $count/$inlinecount to get a count of the number of service endpoints registered in the tenant. Please refer the relevant segment below.

 

New with SAP Cloud Integration September 2019 release (v3.15.x)

The OData API is now enhanced to provide you the 'REST' protocol details in the corresponding service endpoints information. With this increment, API consumer can filter the service endpoints based on Protocol - 'REST'. Please refer the below Adapter/Protocol Type table for details.

 

New with SAP Cloud Integration 8^th July 2019 release (v3.13.x)

The OData API is now enhanced to provide you with the Protocol details except 'REST' in the service endpoints information.

 

OData API to access the service endpoints exposed from Cloud Integration.

This API has been introduced with an aim to support stakeholders and customers who would like to access its service endpoints and various properties from the Cloud Integration to meet their specific use cases or needs.

Benefits:

• Consumers of this API will get all the service endpoints exposed from CPI for a tenant.


• This will be one stop shop to get all the service endpoints available for the tenant.


• Endpoints are accessible for both iFlow and OData service.


• Manual procedure of discovering the service endpoints for the specific tenants has been automated through API call.

Use cases:

You can leverage this API to target many use cases and I would like to depict a few in this blog.

 

Send Purchase orders from S4 HANA to Business partner

This service endpoints API helps you to discover the relevant endpoint that would in turn trigger the Integration Flow to send the Purchase Orders from the S/4HANA cloud system to the respective Business Partner.



 

Employee data replication from SAP SuccessFactors to SAP S/4 HANA

Employee data integration can be triggered to replicate the Employee address details maintained in the SAP SuccessFactors system into the SAP S/4HANA system.

Through the service endpoints API, you can discover the relevant endpoint and can trigger the employee data replication which shall replicate the data to SAP S/4 HANA.



 

Provide businesses with competitive advantage and insights into how to reach and engage with their customer base

SAP offers an integration package that runs on SAP Cloud Integration that allows customers to retrieve the results of social media data queries directly from the social media channels (Twitter) and load them into SAP Hybris Marketing Cloud.

As a result, companies can analyze customers’ conversations and get valuable insights to serve their target audience in a better way.

For many businesses, understanding customer sentiment is a key factor. Organizations spend a considerable amount of time and effort trying to understand sentiment insights so that products and services can be improvised accordingly.

The service endpoints API helps you to trigger the integration flow with the relevant endpoint to extract the results from the Social media data queries.

Through the service endpoints API, you can discover the relevant endpoint and can trigger the integration flow to retrieve the results of social media data queries.



 

API Entity Properties

Listed below are some of the properties of the API entity useful for consumption standpoint.

Property	Description
Name	Name of the item and the identifier field.
Title	Title of the item.
Summary	A short summary of the item that can be used in the list/tile view.
Description	A description of the item.
Version	Version of the item
Documentation	Further documentation describing the API in more detail.
lastUpdated	Timestamp when the item was last updated
apiDefinitions	An array of APIDefinition containing links to the machine-readable API definitions Eg: Open API Specifications files, OData Metadata etc.
entryPoints	An array of EntryPoint of the API.

 

What is an EntryPoint

The table below explains the EntryPoint entity.

Property	Type	Description
Name	String	Name of the entry point.
url	URL	Fully qualified endpoint or the base Path of the API
Type	Enumerated String	Possible values are DEV, TEST, PROD, SANDBOX.

 

What is APIDefinition

The table below explains the APIDefinition entity.

Property	Type	Description
Type	Enumerated String	Name of the API Definition endpoint. Possible values are oas-yaml, oas-json, raml, edmx,wsdl.
url	URL	Fully qualified endpoint to the API Definitions file.

 

Query options supported:

1. $format


2. $expand


3. $select


4. $filter

 

ServiceEndpoints API Examples

The operation of this API is retrieve and it is mapped to the HTTP GET method.

1. https://<tmn url>/api/v1/ServiceEndpoints -- >Returns all the service endpoints for the specific tenant


2. https://<tmn url>/api/v1/ServiceEndpoints?$format=json -- > This will enhance the readability of the service endpoints by providing the json format of the same.


3. https://<tmn url>/api/v1/ServiceEndpoints?$expand=EntryPoints -- > Expands and returns all possible entry points of the API for the specific tenant


4. https://<tmn url>/api/v1/ServiceEndpoints?$expand=ApiDefinitions --> Expands and returns all possible ApiDefinitions of the API for the specific tenant

Additionally, you can also use $select query option:

1. https://<tmn url>/api/v1/ServiceEndpoints?$select=EntryPoints


2. https://<tmn url>/api/v1/ServiceEndpoints?$select=ApiDefinitions

 

ServiceEndpoints API Responses


How to expand and return all possible entry points of service endpoints for the filtered integration flow artifact

Request URL:

https://<tmnurl>/api/v1/ServiceEndpoints?$expand=EntryPoints&$filter=Name eq 'iflow_SOAP'

Note : Name is the Bundle symbolic name of the iFlow project.

Response:



 

How to expand and return all possible APIDefinitions of service endpoints for the filtered integration flow artifact

Request URL:

https://<tmnurl>/api/v1/ServiceEndpoints?$expand=ApiDefinitions&$filter=Name eq 'iflow_SOAP'

Note : Name is the Bundle symbolic name of the iFlow project.

Response:



 

No CSRF Token Handling

This is a HTTP GET call, hence it need not have a X-CSRF token. You can directly invoke the URL from the browser using adequate Authorization.

 

Filter Service Endpoints based on the Protocol.

The OData API is now enhanced to provide you with the Protocol details in the service endpoints information.The Protocol information is the type of the API used, such as, SOAP, REST and ODATA. If applicable, Protocol information will contain the version details as well

Adapter	Protocol Type
SOAP	SOAP
IDoc	SOAP
OData V2	ODATAV2
AS2	AS2
AS4	AS4
HTTPS	REST

You can leverage this enhancement to filter the endpoints registered in the tenant based on the Protocol.

Examples:

• https://<tmn url>/api/v1/ServiceEndpoints?$expand=EntryPoints&$filter=Protocol eq 'SOAP'


• https://<tmn url>/api/v1/ServiceEndpoints?$expand=EntryPoints&$filter=Protocol eq 'ODATAV2'

 

 

• https://<tmn url>/api/v1/ServiceEndpoints?$expand=EntryPoints&$filter=Protocol eq 'REST'

 

Query service endpoints by leveraging following supported query parameters.

 

1. $top - Query option $top=n will retrieve the top n records from the OData service feed/collection. The below example will return the top 5 service endpoints registered in the tenant. Here implicitly $skip would be 0. Example - https://<tmn url>/api/v1/ServiceEndpoints?$top=5.


2. $skip - $skip=x will go with $top=n query option, it will retrieve top n records by skipping the first x records. Here we are using explicit skip 1 and $top of 5 means skip the first service endpoint and then return the next 5 registered service endpoints. Example - https://<tmn url>/api/v1/ServiceEndpoints?$top=5&skip=1.


3. $count - This query request will return the number of count of the service endpoints registered in the tenant. Example - https://<tmn url>/api/v1/ServiceEndpoints/$count.


4. $inlinecount -The other way to get the number of count is using $inlinecount directive to get the count as part of the response body. Example - https://<tmn url>/api/v1/ServiceEndpoints?$inlinecount=allpages.

 

I hope, you can benefit from the enhancements presented in this blog post. In case of questions or feedback, please feel free to comment on this blog.

[adam_kiwon3]

Dear Kamlesh,

Great blog. Is there a reason why only iFlow endpoints are accessible and not the ones of OData Services?

Best regards,
Adam

[kamlesh_zanje]

Dear Adam,

Thanks for appreciating blog. The endpoints are accessible for both iFlow and OData services. I had a re-look and could confirm. Please try this URL and let me know if you face any problem.

https://<tmnurl>/api/v1/ServiceEndpoints

You can as well apply the query option to get the endpoint details of the OData service. Please provide bundle symbolic name of OData service project and invoke below URL.

https://<tmnurl>/api/v1/ServiceEndpoints?$expand=EntryPoints&$filter=Name eq '<Bundle symbolic name of OData Service project>'

Regards,

Kamlesh.

[uwevoigt123]

Hello Kamlesh,

Thanks for your article!

Do you know if there are plans to enhance the API so that Packages or DesignTimeArtifacts can be retrieved?

I see that the itspaces app itself supports some endpoints on odata/1.0/workspace.svc but I cannot use valid OAuth tokens to authenticate.

Uwe

[kamlesh_zanje]

Hello Uwe

Thanks for appreciation.

However, which metadata information of Packages or DesignTimeArtifacts you would like to maintain in this ServiceEndpoints API. Also it would be great, if you share the use cases that you would like to target with these additional details.

 

itspaces API --- odata/1.0/workspace.svc --- is for the internal consumption, not public is nature. But we have plans to make this API public. We will update you once it is available for the external consumption.

 

 

 

[uwevoigt123]

Hi Kamlesh,

 

Thanks for your answer!

My question is not directly regarding the Service Endpoint API but the ODATA API as a whole.

Since the deployment model of integration artifacts, especially integration flows is somewhat cumbersome - we have to develop within the design time workspace, deploy from there and if we move to another stage, I suspect we have to move all artifacts into the respective design time workspaces, modify externalized properties and deploy from there - I wrote a handful of scripts, especially for downloading and pushing to a Git repo and deploying from there without the need to have anything within the production design time workspace (for instance).

Another helpful side effect is that externalized properties can be clearly defined within the Git repository, packaged and deployed in one row.

I do not have an instant need for the itspaces API. However, I have that two scripts to display the packages and design time artifacts that are there in the design time workspace, as a little command line help for developers. In contrast to the rest these both scripts require user authentication and cannot use the existing OAuth token.

Regards,

Uwe

[drvup]

Hi Kamlesh,

I did follow your guideline. Unfortunatley "ServiceEndpoints" isn't available (anymore?) for the API?

Calling our CPI on Cloud Foundry "https://de.it-cpiXXX.cfapps.eu10.hana.ondemand.com/api/v1/ServiceEndpoints"

I receive "Missing message for key 'org.apache.olingo.odata2.api.uri.UriNotMatchingException.NOTFOUND'!"

So I gues, this functionality isn't available anymore / on Cloud Foundry CPI ?

 

Tahnk you for clarification,

Regards,
Cedric

[kamlesh_zanje]

Dear Cedric,

ServiceEndpoints OData API is only available in NEO. This API is not yet available in Cloud Foundry(CF). This is a public limitation in SAP Cloud Integration on CF. We are working towards resolution and will update the availablity of the same via blog and CPI product documentation.

If you face any issue on the usage of ServiceEndpoints API in NEO, please get back to me.

Regards,

Kamlesh.

[former_member661247]

Hi Kamlesh Zanje,

 

Thanks for the Blog! I was trying it out in our CF CPI instance and I get a 'Forbidden' error. Is there any role that I need to assig to my role in order to consume these APIs?

 

Thanks,

Fran

[kamlesh_zanje]

Hello Fran,

May be you can elaborate your query a bit. Are you getting Forbidden error while trying to invoke the service endpoints OData API URL ?

URL --- > https://<tmn url>/api/v1/ServiceEndpoints

or while trying to invoke the metadata url of the service endpoints API response ?

Which authentication type you have leveraged, Basic or OAuth ?  Please refer this help document for details -  https://help.sap.com/viewer/368c481cd6954bdfa5d0435479fd4eaf/Cloud/en-US/8db3d5141cd644019f0cf244e2a...

Service Endpoints OData API is already available in Cloud Foundry many months back and fundamentally it should work.

You can reach out to me -- > kamlesh.zanje@sap.com or report a ticket on LOD-HCI-PI-WT-IFL.

Regards,

Kamlesh.

[kamlesh_zanje]

Hello Cedric

Hope you are aware, ServiceEndpoints OData API is already available in CF many months back.

Regards,

Kamlesh.

[former_member661247]

Hi Kamlesh,

I was leveraging OAuth authentication and was receiving that error because I was missing the necessary roles missing in my service instance to execute the API call.

I came across the docu that you have shared and I was able to make it work following those instructions.

Thank you,

Fran

 

[kamlesh_zanje]

Thanks for reply Fran. Happy to hear that your problem is solved.

[joao_doe]

Hello Kamlesh,

you mentioned in this post that there are plans to make the workspace.svc public in 2019. Is this still on the roadmap? Can you hint when can we expect such release?

I'm thinking it would be a great way to overcome some limitations on the current official api such as downloading script collections, odata apis, rest apis, message mappings and so on. As far as I know, only download of iflows and value mappings is supported. Only through downloading the whole package we could have every artifact but even then only if those artifacts are not in draft status.

Also, can you clarify why there are services to load the security material through ITApiFactory.getApi but not to get the datasource throught camel context lookup? I'm thinking if we want to connect to a db via script and use an existing datasource available on jdbc material, it doesn't seem to be a way to reuse it.

Many thanks for your help and kudos to the cloud integration team.

[former_member90082]

Hi Kamlesh,

 

Thanks for the great blog for sharing the information, I am wondering is there anyway to get the ProcessDirect 'Address' listed?

the reason to ask is that if we have multiple person work on similar function, the address may be giver duplicated, it is very hard to know which deployed iflow occupied the name.

 

Best Regards,

Wei

[filipe_rieger]

Hi Kamlesh,

There are many other Adapter types besides the ones listed in your blog.

Process Direct, XI, 3rd Party Adapter's like Salesforce etc.

Any plans to enhance the search with those Adapter's too?

[kamlesh_zanje]

Thanks Filipe for sharing your feedback. There is no plans to enhance the service endpoints API in 2023 to fetch the registered endpoints based on the process direct, XI and custom adapters. Let me discuss this ask with my program.

[kamlesh_zanje]

Thanks Weifor sharing your feedback. There is no plans to enhance the service endpoints API in 2023 to fetch the registered endpoints based on the process direct. Let me discuss this ask with my program.

[kamlesh_zanje]

Hello Joao,

OData remote ( aka public) APIs are already available for script collection and message mapping artifacts.

You can refer the api.sap.com for more details on the supported APIs and its operations.

https://api.sap.com/api/IntegrationContent/resource

Coming back to your second question why the existing Package public API doesn't allow the export of package if atleast one artifact is in the draft state. Basically this behaviour is as per the design. Package public API to export the package is meant to support the transport of the package from landscape (Dev -- > Test -- > Production) and fundamentally if the artifact is in the draft state it means it is still under-developed and not ready to transport across different landscape.

Maybe you can elaborate in detail why you would like to transport the package if artifact is in draft state? Probably help me to understand your use case.

Regards,

Kamlesh.

[kamlesh_zanje]

Hello Uwe,

When you want to manually transport the package across the landscapes (Dev-- > Test--- > Production), you can use the package export , import public APIs which export the package and import the package content in the target system without overriding the configured parameters of the integration flows in the target tenant. You really don't need to modify the externalized parameters. Basically the configured parameters in the target tenant where you are importing the exported package will remain as-is.

Refer the Integration Packages - Design section from the below api business hub url. Let me know if you have any follow up questions.

https://api.sap.com/api/IntegrationContent/resource

Regards,

Kamlesh.