SAP Business ByDesign (ByD) is designed as open cloud solution with a comprehensive set of APIs. The API portfolio splits into multiple API types which are designed for specific integration rationales and API usage patterns.
This may raise two questions:
- Which APIs are available in SAP Business ByDesign?
- For which purpose shall I choose which API type?
Basically you could think about the ByD API portfolio as a “buffet”: Know want you want to have. Know the taste of the buffet offerings. And make a qualified choice.
In this blog post I want to give you an overview of the “API buffet”. I talk about typical API usage pattern, the "flavor" of API types in SAP ByDesign and give some guidance for a qualified choice to save costs and reduce complexity of your SAP ByDesign integration or extension project.
API Usage Pattern
Basically we have the following four integration rationales and 11 API usage patterns in mind when talking about SAP ByDesign APIs. Assiging your use case to one of the API usage pattern helps a lot to make a qualified choice later on.
Data Integration
Data integration empowers you to access business objects, the main carrier of business logic in ByD, and to extend ByD by your own innovations, applications and services.
API Usage Pattern:
- Remote Access to Business Objects
A remote system queries, reads, creates, updates, deletes or performs actions on ByD business objects and business documents. Typically the remote system passes all relevant data in a single roundtrip using a technical user for authentication. - Interactive Access to Business Objects
A UI-like remote application or system interactively queries, reads, creates, updates, deletes or performs actions on ByD business objects and business documents. The remote application orchestrates the access to the business objects for use cases like search business objects and business object nodes, navigate through the business object structure, and any operations on business object nodes following an interactive approach (read > update > follow association > read > update …). - Subscribe to ByD Events
A remote system subscribes to ByD events.
Process integration
Process integration enables you to automate business processes and business collaboration scenarios across system boundaries by connecting systems and business partners.
API Usage Pattern:
- Remote Access to Trigger a Business Process in ByD
A remote system invokes a business process in ByD. The business process may represent the communication between a business partner and a company in ByD (business collaboration), as well as process chain that has been started in the remote system and shall be continued in ByD. - ByD invokes a Business Process Task in a remote system
ByD invokes a Business Process Task in a remote system. The business process may represent the communication between a company in ByD and a business partner (business collaboration), as well as process chain that includes a process step in a remote system.
Analytical integration
Analytical integration enables you connect ByD to digital board rooms, global business intelligence solutions and augmented analytics for insights-driven decision making and planning.
API Usage Pattern:
- Mass Data Extraction of Analytical Raw Data
A remote system extracts analytical raw data free of redundancies in flat tables from ByD. The raw data is processed, combined and formatted in the remote system. - Extend ByD built-in analytics by external data sources
A remote system feeds ByD with external data to enhance ByD analytical data sources for ByD built-in analytics. - Remote Access to pre-processed Analytical Data
A remote system extracts formatted analytical data pre-processed by ByD. The remote system may extract a ByD analytical model as a cube incl. semantics like key figures and language-dependent texts, ready to be processed by 3rd-party clients, or the remote system extracts analytics result sets incl. aggregations and key figures, ready to be displayed for users. - Live Access to Analytical Data
A remote system has no own persistency and operates on ByD as persistency layer for analytical use cases.
UI integration
UI integration enables a seamless user experience across applications including navigation and mashups.
API Usage Pattern:
- Navigation ByD UI to 3rd-party UI
Users navigate from a ByD screen to an external application UI incl. deep linking and parameterized URLs. - Navigation 3rd-party UI to ByD UI
Users navigate from an external application UI to a ByD UI screen. - Embed 3rd-party web services, screens and information in ByD UIs
Embed a 3rd-party screen, RSS feed, web service, media or other sources in a ByD screen and exchange data between the external service and ByD business object documents.
API Portfolio
SAP Business ByDesign provides APIs and integration capabilities for all API usage pattern. In the following I focus on APIs for server side integration scenarios.
Web Service APIs (SOAP)
Web service APIs enable read and write access to ByD business objects. Web service APIs are tailored to integrate systems using a minimal number of roundtrips. Sophisticated delta handling, concurrency controls and idem potency services supports you to ensure smooth system collaborations. All services are stateless, synchronous SOAP services.
Using query services you can query and read business objects and get business object data in an hierarchical xml format. You can specify the data to be returned in the query request using “Requested Elements”. Paging capabilities allow you to read large amounts of data in multiple packages.
Manage services can be used to create, update, delete and to invoke actions on multiple deeply structured business objects in a single web service request. Most manage services support a simulation mode (check) as separate operation as well.
Configuration and Authorization:
Web service APIs are configured using communication arrangements:
- Work center view Application and User Management - Communication Systems: Create a communication system representing the remote system. Each communication system generates a technical communication user for authentication.
- Work center view Application and User Management - Communication Scenarios: Create a communication scenario and add relevant web service APIs. The communication scenario generates an authorization role that is assigned to the communication user in the next step.
- Work center view Application and User Management - Communication Arrangements: Create a communication arrangement using the communication scenario and communication system and enter the credentials of the communication user.
As result the communication user is authorized to access all web service operations listed in the communication arrangement. The communication arrangement contains all information needed to consume the services incl. access URLs, WSDL downloads and service documentations. - In the communication arrangement you can download the WSDL, display the web service documentation and change the service credentials.
Authentication:
- User type: Technical user (communication user)
- Authentication protocols:
- Basic authentication (user/password)
- Certificates (You can upload a public key certificate that has been provided by the communication partner or create and download a PKCS#12 key pair file from ByD).
Some web service APIs can be accessed using business users as well. Typically this is possible if the web service is used for user initiated remote interactions, such as Excel uploads or the Outlook integration. For such scenarios the web service authorization is linked to the work center view which contains the remote interaction. The authentication protocols are the same as for Custom Web Service APIs (see below).
Extensibility:
In general you can add extension fields to Web service APIs using the ByD adaptation mode (for extension fields added by key users) or the SAP Cloud Applications Studio (if the extension field itself has been added in the same SAP Cloud Applications Studio project). However, some Web Service APIs do not support extensibility; please check the specific Web Service API documentation for more details.
FAQ:
- Does SAP plan to replace SOAP Web Service APIs by OData?
No, we have no plans to replace SOAP Web Services APIs by OData. SOAP and OData services are designed for different usage pattern (as described in this blog post). - What shall I do in case of questions or if I look for some examples?
Post your question in the SAP Business ByDesign Community (common user tags “byd api”, “byd web service” and “byd integration”). - What shall I do if a field is missing in a web service API?
Open a ByD incident and request to add the missing field; refer to “solution completeness”. - What shall I do if an API is missing?
Check possible alternatives such as Custom Web Service APIs or OData API for Business Objects or open an improvement request on the Customer Influence page for SAP ByDesign.
More information:
- API Package for SAP Business ByDesign (SAP API Business Hub)
- SAP Business ByDesign Web Service Documentation (SAP API Business Hub)
- SAP Business ByDesign Help Portal >> Web Service APIs
Examples:
- Change Product Tax Classifications using Web Service APIs (SAP Community)
- Create ByD Sales Orders using Web Services (SAP Community)
- How to create ERS Invoices using ByD Web Service APIs (SAP Community)
- Read and Write ByDesign Attachments using Web Services (SAP Community)
- Mass Changes of ByD Data using Excel and ByD Web Services (SAP Community)
- How to get ByDesign Code Lists via Web Service QueryCodeListIn (SAP Community)
- Integrate SAP ByDesign with Point-of-Sales Systems (SAP Community)
- SAP Community blog posts about ByD Web Service APIs: https://blogs.sap.com/tag/byd-web-service-api/
OData API for Business Objects (REST)
The OData API for Business Objects is designed for user centric applications to access ByD business objects such as mobile apps or freestyle UIs using ByD as backend. The APIs provide you with additional metadata to ease UI development, such as localized field labels, code descriptions and value help support. In addition the API supports typical navigations between business object nodes like "from header to detail", navigations to associated business objects (for example "from sales order item to product details") and efficient fine grained data access. The authentication using business users enable you to combine frontend single sign-on and principal propagation using OAuth to benefit from the role-based authorization management of ByD.
Using the work center view OData Services, key users are empowered to decide which business objects, business object elements and actions are exposed via OData APIs. Using OData you can access the OData-enabled part of the public solution model of ByD, plus extension fields, add-on business object extensions, and custom business objects created using the SAP Cloud Applications Studio.
Configuration and Authorization:
Work center view Application and User Management - OData Services: Expose the ByD business object including nodes, elements and functions as Custom OData Service and assign your service to a work center view. As result all ByD users with access to the assigned work center view are authorized to access the OData service.
Authentication:
- User type: Technical user (communication user)
- Authentication protocols:
- Basic authentication (user/password)
- Certificates (You can upload a public key certificate that has been provided by the communication partner or create and download a PKCS#12 key pair file from ByD).
- User type: Business users (employees or service agents)
- Authentication protocols:
- Basic authentication (user/password)
- Certificate (user logon certificate)
- OAuth 2.0 SAML Bearer authentication
- SAML 2.0 (Identification by user ID or e-mail address; specific endpoint for single sign-on: <sso-hostname>/sap/byd/odata-sso/…)
Extensibility:
Extension fields can be added to custom OData services using the work center view OData Services. Furthermore you can create custom OData services for custom business objects (created using the SAP Cloud Applications Studio) using work center view OData Services as well.
FAQ:
- What shall I do if I need an example request or if I have questions?
Check if you find a suitable example in the GitHub repository linked in blog post OData API Usage Samples. Post your question in the SAP Business ByDesign Community (common user tags “byd api”, “byd odata” and “byd integration”). - What shall I do if a property or function is not available in the Custom OData service modeler?
Open a ByD incident and request to enhance the public solution model (see blog post SAP ByDesign Public Solution Model).
More information:
- SAP Business ByDesign Help Portal >> search with key words “OData User Guide”
- Configure OAuth 2.0 for SAP ByDesign OData Services (SAP Community)
Examples:
- OData API Usage Samples (SAP Community)
- Extend SAP ByDesign using SAP Cloud Platform HTML5 Applications (SAP Community)
- OData Example: Read and Write Product Purchasing Data (SAP Community)
- Create ByD Sales Orders using Alexa (SAP Community)
- SAP Business by Design – How to Create an OData Service (Youtube)
- SAP Community blog posts about ByD OData: https://blogs.sap.com/tag/byd-odata/
Business Objects Events
As a key user you can configure event notifications such that external systems can subscribe to ByD business object events. In result ByD sends event messages to the specific endpoint of the external system.
Event subscriptions can be used for all kind of loosely coupled event-based integration scenarios such as event-driven side-by-side extensions, to trigger real-time data replication scenarios, or to trigger actors in IoT scenarios.
Event specification:
| id: | Unique identifier of the event. |
| specversion: | The version of the event specification used by the event message. |
| source: | Identifies the instance the event originated in (contains the ByD tenant ID). |
| type: | Describes the type of the event related to the source the event originated in (the ByD business object, business object node and the event type). |
| datacontenttype: | Content type of the event data. |
| time: | Timestamp of when the event has been raised. |
| data: | Object ID of the business object root node (root-entity-id) and object ID of the business object node (entity-id). These object IDs can be used to access the corresponding business object using the OData API for business objects. |
Configuration and monitoring:
Using the work center view "Application and User Management - Event Notification" you can add subscribers and configure event subscriptions for create, update and delete events of business objects and business objects nodes that are released in the ByD public solution model.
Note: Almost all ByD business objects have administrative information like a last changed date/time on root level, which reflects all business object changes. This means subscribing to update-events on root level triggers an event message for all business object changes.
Using the work center view "Application and User Management - Event Notification Monitoring" you can monitor the status of event messages and resend or cancel event messages, and download event payloads.
Authentication:
- Basic authentication (user ID and password)
- Client certificate (download a PKCS#12 key pair file from ByD)
- OAuth 2.0
Extensibility:
You can create event subscriptions for custom business objects (created using the SAP Cloud Applications Studio) using work center view Event Notification the same way as for standard business objects. Furthermore, business object events are raised in case of changes to key user or add-on extension fields as well.
Example event payload:
{
"specversion": "1.0",
"source": "/ROT/sap.byd/000000000123456789",
"type": "sap.byd.SalesOrder.ItemProduct.Created.v1",
"id": "00163e73-06a3-1eeb-addc-b49adfaf4097",
"time": "2021-05-17T07:58:14Z",
"datacontenttype": "application/json",
"data": {
"root-entity-id": "00163E7306A31EEBADDCB17C70E9204C",
"entity-id": "00163E7306A31EEBADDCB32EB797A04C"
}
}More information:
- SAP Business ByDesign Help Portal >> search with key words “Event Notification”.
B2B and A2A Interfaces (SOAP)
SAP Business ByDesign offers a set of business scenarios with remote communication capabilities to business partners or applications running on different systems. These capabilities are provided as pre-packaged communication scenarios in two flavors:
- Application-to-Application (A2A) communication scenarios
- Business-to- Business (B2B) communication scenarios
A2A and B2B interfaces are SOAP interfaces mostly using asynchronous messaging. Depending on the supported protocols on service interface level, standards-based XML communication can be conducted using multiple application protocols: SAP XI 3.0, SAP IDoc over SOAP, WSRM 1.1 and plain SOAP 1.1.
Inbound interfaces support parallelization, exactly once in order processing, idem potency and forward error and conflict handling to simplify the resolution of semantical communication issues.
Outbound interfaces provide predefine message types and interface signatures that have to be supported by the provider application; the definition WSDL can be downloaded in the ByD communication arrangement.
B2B communications are designed to exchange business documents between business partners, which means:
- B2B outbound interfaces are embedded in the ByD output management.
- B2B message types reflect the sender as well as receiver point of view. For example suppliers can be identified by the ByD internal ID, by a customer ID at supplier, by a Global Location Number (GLN) or by a tax number.
- ByD B2B outbound and inbound interfaces are aligned such that two companies using ByD can easily communicate with each other without any middleware or message mappings.
Configuration and Authorization:
A2A and B2B interfaces are mostly available in context of a pre-packaged communication scenario.
- A2A interfaces:
- Work center Business Configuration: Scope the pre-packaged communication scenario by activating the corresponding scoping question.
- Work center view Application and User Management - Communication Systems: Create a communication system representing the remote system. Each communication system generates a technical communication user for authentication.
- Work center view Application and User Management - Communication Arrangements: Create a communication arrangement using the standard communication scenario and the communication system created in step 2, and enter the credentials of the communication user. For outbound communications you can additionally enter the service hostname, URL and credentials, and check the connection.
- In the communication arrangement you can download the WSDL, display the web service documentation and change the service credentials.
- B2B interfaces: B2B configurations reflect a communication between a company and a business partner. Therefore any configuration is specific for those parties as well. The following tasks need to be done:
- Work center Business Configuration: Scope the pre-packaged communication scenario by activating the corresponding scoping question.
- Maintain the master data representing the company and the business partner (account or supplier). Enter standard IDs (Global Location Number or DUNS Number) for both communication parties.
- Create a communication arrangement for the technical communication setup between the communication parties. Use the standard communication scenario in the communication arrangement.
- For outbound communications select the “XML” as output channel in the business partner collaboration settings.
Authentication:
- User type:
- A2A inbound interfaces: Technical user (communication user associated to a communication system)
- B2B inbound interfaces: Technical user (communication user associated to a business partner)
- A2A and B2B outbound interfaces: User and credentials are maintained in the communication arrangement
- Authentication protocols:
- Basic authentication (user/password)
- Certificate (You can upload a public key certificate that has been provided by the communication partner or create and download a PKCS#12 key pair file from ByD).
More Information:
- SAP Business ByDesign Help Portal >> Integration Scenarios
- SAP Business ByDesign Help Portal >> Custom Data Integration Guide
Examples:
- Setup B2B Sales Order Integration with SAP Business ByDesign (SAP Community)
OData API for Reports (REST)
The OData API for Reports is tailored for remote access to pre-processed analytical data: A remote system extracts formatted analytical data pre-processed by ByD. The remote system may extract a ByD analytical model incl. semantics like key figures and language-dependent texts, ready to be processed by clients, or the remote system extracts analytics result sets incl. aggregations and key figures, ready to be displayed for users.
Using the OData API for Reports you can access standard reports provided by SAP, reports created by key users and business users, and reports created as part of a ByD add-on using the SAP Cloud Applications Studio.
Configuration and Authorization:
All reports provided by SAP, Partners and key users can be accessed using OData without any configuration. The system verifies if the logon user is authorized to access the report and the data according the ByD role-based access management.
Authentication:
- User type: Business users (employees or service agents)
- Authentication protocols:
- Basic authentication (user/password)
- Certificate (user logon certificate)
- OAuth 2.0 SAML Bearer authentication
- SAML 2.0 (Identification by user ID or e-mail address; specific endpoint for single sign-on: <sso-hostname>/sap/byd/odata-sso/…)
Extensibility:
The OData API for reports provides access to all standard and custom reports incl. extension fields that have been added to those reports out of the box.
More information:
- SAP Business ByDesign Help Portal >> Search with key words "Retrieving Analytics Data Using OData"
- OData for SAP Business ByDesign Analytics (SAP Community)
- Using Filter and Selection Parameter in ByD OData for Analytics (SAP Community)
Examples:
- OData API Usage Samples (SAP Community)
- Alexa meets SAP Business ByDesign (SAP Community)
OData API for KPIs
The OData API for KPIs (Key Performance Indicator) is tailored for remote access to pre-processed analytical data: A remote system extracts current business KPI values from ByD including current values, target values, reference values, delta information as absolute value and percentage, thresholds, trend, and improvement direction.
The remote system may display the KPIs on a global analytical dashboard or use the included property Execution Date/Time to build a KPI history by periodically extracting KPI values.
Configuration and Authorization:
All KPIs provided by SAP, Partners and key users can be accessed using OData without any configuration. The system verifies if the logon user is authorized to access the KPI and the data according the ByD role-based access management.
Authentication:
- User type: Business users (employees or service agents)
- Authentication protocols:
- Basic authentication (user/password)
- Certificate (user logon certificate)
- OAuth 2.0 SAML Bearer authentication
- SAML 2.0 (Identification by user ID or e-mail address; specific endpoint for single sign-on: <sso-hostname>/sap/byd/odata-sso/…)
Examples:
- Get metadata:
myXXXXXX.sapbydesign.com/sap/byd/odata/analytics/kpi/Kpi.svc/$metadata?sap-label=true&sap-language=de - Get KPI details:
myXXXXXX.sapbydesign.com/sap/byd/odata/analytics/kpi/Kpi.svc/Kpi?$format=json&sap-language=de - Get KPI value (Total Active Order Volume):
myXXXXXX.sapbydesign.com/sap/byd/odata/analytics/kpi/Kpi.svc/KpiValue?$format=json&$filter=Id eq 'CRMSLOIB_Q0001_SOVOLUME' - Get KPI value (Overdue Receivables):
myXXXXXX.sapbydesign.com/sap/byd/odata/analytics/kpi/Kpi.svc/KpiValue?$format=json&$filter=Id eq 'FINDUE0001'
OData API for Data Sources (REST)
The OData API for Data Sources is designed to extract analytical raw data. A remote system extracts ByD analytical raw data in flat tables, free of redundancies from ByD. The analytical raw data is then processed, combined and formatted in the remote system. Typically such remote systems are central business analytics application such as SAP Analytics Cloud.
Using the OData API for Data Sources you can extract standard basic and combined data sources provided by SAP, created by key users, and created as part of a ByD add-on using the SAP Cloud Applications Studio.
Configuration and Authorization:
- Work center view Business Configuration - Implementation Project: Activate the OData API for analytical data sources in the scoping questions: Built-in Services and Support >> System Management >> Analytics >> select the question Do you want to enable analytical OData services for data sources?
- Work center view Application and User Management - Communication Systems: Create a communication system representing the remote system. Each communication system generates a technical communication user for authentication.
- Work center view Application and User Management - Communication Arrangements: Create a communication arrangement using the communication scenario “Analytics DataSources OData” and the communication system and enter the credentials of the communication user.
- Work center view Business Analytics - Data Sources: Select and expose the data sources which you want to extract.
- In the communication arrangement you can change the service credentials if needed.
Authentication:
- User type: Technical user (communication user)
- Authentication protocols:
- Basic authentication (user/password)
- Certificates (You can upload a public key certificate that has been provided by the communication partner or create and download a PKCS#12 key pair file from ByD).
Extensibility:
The OData API for data sources provides access to standard and custom data sources incl. extension fields that have been added to those data sources out of the box.
More information and examples:
- SAP Business ByDesign Help Portal >> Search with key words "Retrieving Analytics Data Using OData"
- OData API Usage Samples (SAP Community)
Operational Data Provisioning API (SOAP)
Similar to the OData API for Data Sources, the ByD Operational Data Provisioning Interface (ODP interface) provides analytical raw data (data sources). The OPD interface is a SOAP API according the SAP BW/4HANA Operational Data Provisioning specification to extract data sources for the purpose to connect ByD with a SAP Business Warehouse (SAP BW). The ByD ODP interface supports the Fetch-Data-Direct pattern and the Open-Fetch-Close pattern (paging). Due to the fact that all ByD analytical data is live data without delta-stores, the ByD OPD interface does not support delta extractions.
Using the ODP Interface you can extract standard basic and combined data sources provided by SAP, created by key users, and created as part of a ByD add-on using the SAP Cloud Applications Studio.
Configuration and Authorization:
- Work center view Business Configuration - Implementation Project: Activate the ODP Interface in the scoping questions: Communication and Information Exchange >> Business Process Management >> Integration with SAP ERP for Subsidiaries >> select the question Do you want to make analytics data from the solution available to a central Business Warehouse system in SAP ERP?
If required you may additionally select the question Do you want to view text fields upto 1024 characters when making analytics data available to an SAP NetWeaver BW system?
- Work center view Application and User Management - Communication Systems: Create a communication system representing the remote system. Each communication system generates a technical communication user for authentication.
- Work center view Application and User Management - Communication Arrangements: Create a communication arrangement using the communication scenario “Analytics Integration” and the communication system and enter the credentials of the communication user.
- Work center view Business Analytics - Data Sources: Select and expose the data sources which you want to extract.
- In the communication arrangement you can download the WSDL and change the service credentials.
Extensibility:
The ODP interface provides access to standard and custom data sources incl. extension fields that have been added to those data sources out of the box.
Authentication:
- User type: Technical user (communication user)
- Authentication protocols:
- Basic authentication (user/password)
- Client certificates (You can upload a public key certificate that has been provided by the communication partner or create and download a PKCS#12 key pair file from ByD).
More information and examples:
- SAP Business ByDesign Help Portal >> Integration Scenarios >> Analytics Integration with SAP Business Warehouse
- Access ByD Data Sources using the ByD ODP Interface (SAP Community)
Analytical data upload into cloud data sources (SOAP)
In ByD you can create Cloud Data Sources to extend the ByD build-in analytics by external data sources. Cloud data sources can be combined with ByD data sources and used to create custom reports.
The SOAP API to upload external data into cloud data sources can be used to insert new data records, modify existing records, delete records, and replace all existing data of a cloud data source.
Configuration and Authorization:
- Work center view Application and User Management - Communication Systems: Create a communication system representing the remote system. Each communication system generates a technical communication user for authentication.
- Work center view Application and User Management - Communication Arrangements: Create a communication arrangement using the communication scenario “Analytics Data Upload” and the communication system and enter the credentials of the communication user.
- In the communication arrangement you can download the WSDL and change the service credentials.
Authentication:
- User type: Technical user (communication user)
- Authentication protocols:
- Basic authentication (user/password)
- Certificates (You can upload a public key certificate that has been provided by the communication partner or create and download a PKCS#12 key pair file from ByD).
More information:
- SAP Business ByDesign Help Portal >> Search with key words "Create and Edit a Cloud Data Source“
Analytical data upload into cloud data sources (REST)
In ByD you can create Cloud Data Sources to extend the ByD build-in analytics by external data sources. Cloud data sources can be combined with ByD data sources and used to create custom reports.
The OData API to upload external data into cloud data sources basically serves the same purpose as the corresponding SOAP API.
Using the OData API you can create, change and delete cloud data source records. Furthermore you can clear the complete data source (delete all records).
Configuration and Authorization:
- Work center view Application and User Management - Communication Systems: Create a communication system representing the remote system. Each communication system generates a technical communication user for authentication.
- Work center view Application and User Management - Communication Arrangements: Create a communication arrangement using the communication scenario “Analytics Data Upload” and the communication system and enter the credentials of the communication user.
- In the communication arrangement you can change the service credentials if needed.
Authentication:
- User type: Technical user (communication user)
- Authentication protocols:
- Basic authentication (user/password)
- Client certificates (You can upload a public key certificate that has been provided by the communication partner or create and download a PKCS#12 key pair file from ByD).
More information:
- SAP Business ByDesign Help Portal >> Search with key words "Create and Edit a Cloud Data Source“
Custom Web Service APIs (SOAP)
The SAP Cloud Applications Studio provides a wizard to create custom web service interfaces with operations to create, read, update, delete, query and invoke actions on ByD business objects. Using custom web service APIs you can access business objects, nodes, elements, queries and actions that are exposed in the public solution model of ByD. Furthermore you can create custom web service APIs for custom business objects created using the SAP Cloud Applications Studio.
Similar to standard Web Service APIs, Custom Web Service APIs are stateless, synchronous SOAP services and support a sophisticated delta handling, concurrency controls and idem potency.
Configuration and Authorization:
The SAP Cloud Applications Studio provides a wizard to generate Custom Web Service APIs in 2 steps: 1. Create a view on the business object, 2. Create web service operations (create, update, delete, read, query and action) and refine the operations signature.
Authentication:
- User type: Technical user (communication user)
- Authentication protocols:
- Basic authentication (user/password)
- Certificates (You can upload a public key certificate that has been provided by the communication partner or create and download a PKCS#12 key pair file from ByD).
- User type: Business users (employees or service agents)
- Authentication protocols:
- Basic authentication (user/password)
- Certificate (user logon certificate)
- OAuth 2.0 SAML Bearer authentication (specific endpoint for access with security session: <hostname>/sap/ap/srt/scs/<service>)
- SAML 2.0 (Identification by user ID or e-mail address; specific endpoint for access with security session: <sso-hostname>/sap/ap/srt/scs/<service>)
- Authentication protocols:
Extensibility:
Custom Web Service APIs can include extension fields and custom business objects that have been created using the SAP Cloud Applications Studio.
More information:
- SAP Cloud Applications Studio Help Portal >> SAP Cloud Applications Studio – Library >> Developer Desktop >> Web services
- SAP Business ByDesign Web Service Documentation (SAP API Business Hub)
- SAP Cloud Applications Studio Community
External API Consumption (REST and SOAP)
Using the SAP Cloud Applications Studio you can embed the consumption of external REST and SOAP web services in the business logic of ByD. This provides you with the possibility to trigger external processes and to incorporate external web services in ByD in-application extensions.
If you combine external API consumption with the capability to create synchronous or asynchronous message-based communications between standard and custom business objects you get a very powerful and flexible tool to build integration scenarios initiated by ByD.
More information:
- SAP Cloud Applications Studio Help Portal >> SAP Cloud Applications Studio – Library >> Developer Desktop >> Web services >> External Web Service Integration
- SAP Cloud Applications Studio Help Portal >> SAP Cloud Applications Studio – Library >> Developer Desktop >> Service Integration
- SAP Cloud Applications Studio Community
Examples:
- Concept idea for custom real-time data replication scenarios (SAP Community)
- How to get SAP Business ByDesign events in a loosely coupled solution
(SAP Community) - Bridging the event pub/sub for SAP Business ByDesign with an internal push approach (SAP Community)
“Make a qualified choice”
Chosing the “right” API is no binary thinking, but rather a qualified decision. Based on your use case there is a first choice (best-fit), a good alternative (good fit) and in some cases you have to understand the use case in detail to come to a conclusion (case-by-case decision). The following API map may help you to find the best API for your purpose or to find a good alternative in case the first choice API type does not provide the API you need.
Example 1: Mobile (hybrid) application for a company address book
- OData can be easily consumed by HTML5 applications (e.g. SAP Cloud Platform Fiori apps) with minimal overhead, excellent development tool support, business user logon, principal propagation and role-based authorization checks, and navigation along business object structures.
- Web service APIs can be used as well, but require a higher development effort and communication overhead because of the Soap protocol; furthermore authentication by technical user means less detailed authorization checks.
Example 2: Master data replication for products (external system to ByD)
- Web service API enable you to create and update products in a single roundtrip – the web service process agent in ByD takes over all parts of the choreography needed – just hand-over the xml with the target state of the object.
- OData can be used as well, but keep in mind that for updates many roundtrips are needed to address several business object nodes and actions. The communication choreography needs to be implemented on consumer side.
Example 3: Purchase order integration with a vendor
- The B2B interface for purchase order integration is designed for this purpose, integrated in the ByD output management with a business partner based receiver determination and forward error and conflict handling for purchase order acknowledgements.
- The 3rd-party A2A outbound interface supported by the output channel External System and communication scenario Output Management XML Integration can be used to delegate the communication with the customer to a middleware or 3rd-party output management system.
- Web service APIs might be an option as well, but requires a mediated pull/push and the communication is not displayed in the documents output history. Furthermore you may have to decide how to address the regular output management, which remains in place while using Web service APIs.
Example 4: You receive an invoice from your vendor as xml messages
- B2B is best fit and designed for this purpose.
- The web service API for supplier invoices can be used as well, because the business object itself supports forward error handling by supplier invoice exceptions, however the service consumer needs to provide error handling capabilities to manage rejected web service calls.
In general you may take into account the following API qualities to make a qualified choice:
Protocol (Soap or REST/OData), synchronous vs. asynchronous communication, idem potency, quality of service (EOIO, WSRM), state management, authentication, service orchestration and mediation, ID and key management, error and conflict handling, delta handling and concurrency control, data volumes, configuration (communication partner, receiver determination), …
- SAP Managed Tags:
30 Comments
