SAP Cloud Integration – OData API for accessing the service endpoints
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 8th 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.
- 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.
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.
|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.
|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.
|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:
ServiceEndpoints API Examples
The operation of this API is retrieve and it is mapped to the HTTP GET method.
- https://<tmn url>/api/v1/ServiceEndpoints — >Returns all the service endpoints for the specific tenant
- 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.
- https://<tmn url>/api/v1/ServiceEndpoints?$expand=EntryPoints — > Expands and returns all possible entry points of the API for the specific tenant
- 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:
- https://<tmn url>/api/v1/ServiceEndpoints?$select=EntryPoints
- 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
https://<tmnurl>/api/v1/ServiceEndpoints?$expand=EntryPoints&$filter=Name eq ‘iflow_SOAP’
Note : Name is the Bundle symbolic name of the iFlow project.
How to expand and return all possible APIDefinitions of service endpoints for the filtered integration flow artifact
https://<tmnurl>/api/v1/ServiceEndpoints?$expand=ApiDefinitions&$filter=Name eq ‘iflow_SOAP’
Note : Name is the Bundle symbolic name of the iFlow project.
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
You can leverage this enhancement to filter the endpoints registered in the tenant based on the Protocol.
- 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.
- $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.
- $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.
- $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.
- $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.