- SAP Managed Tags:
<<Japanese Version is here>>
This blog is the second part of the blog series "How to extend SAP S/4HANA with SAP Cloud Platform". I will explain how to find an API for SAP S/4HANA on-premise.
As mentioned in the previous blog , there are two types of S/4HANA Extensions: In-App extensibility and Side-by-Side extensibility. In the case of Side by Side Extensiblity, an application developed with Java, JavaScript (Node.js), Python, etc. runs on SAP Cloud Platform, and connects to S/4HANA via API (Application Programming Interface). Therefore, it is necessary to find out what kind of API exists in SAP S/4HANA and how to use it.
Currently the most common and latest APIs of SAP S/4HANA are based on OData or SOAP. Let's look at the characteristics of each API type one by one.
OData is a standard REST-based protocol and is officially called Open Data Protocol. Previously promoted mainly by Microsoft, it became the OASIS standard in 2014. Most APIs of SAP S/4HANA as of now are based on OData V2. Since it is a REST protocol, CRUD (Create, Read, Update, Delete) of each OData API supports HTTP POST, GET, PUT/PATCH, DELETE, while some Odata APIs are only for read-only. Most of the latest S/4HANA APIs are OData based ones, so it's a good idea to look for OData APIs first.
SOAP is a Web Service protocol that was popular in the 2000s and is still used today. Once it was heavily used as a core technology of SOA (Service Oriented Architecture), and there are many SOAP-based APIs in S/4HANA. It is the same as OData in that it is based on HTTPS, but it is necessary to have an XML container called SOAP Envelope in the HTTP Body, and to put the XML (SOAP Body) that is the content in it. In many cases, SOAP Client is generated with a metadata file called as WSDL (Web Service Description Language).
Most of the APIs existing in SAP API Business Hub introduced here are provided in OData or SOAP format.
BAPIs and IDocs are the legacy APIs that have long been used since the era of SAP R/3 and SAP ECC. These are not listed in SAP API Business Hub, and it is necessary to check them in the system of each S/4HANA and/or online help.
BAPI (abbreviation of Business Application Programming Interface) is a legacy API implemented in the form of functions called SAP Function Modules. It is possible to be called from outside using SAP's own protocol called RFC (Remote Function Call). If you want to call BAPI from Java, you can use the wrapper library called as JCo (Java Connector, pronounced as Jay-co) and you can use .Net Connector (= NCo) for .Net based apps . BAPI is logically defined as a method of Business Object * ( the objects such as sales order good receipts, material masters, etc. that are defined in S/4HANA such as documents and masters). * This Business Object is not relevant to BI Tools SAP Business Objects
IDoc is an abbreviation for Intermediate Document.
Originally, IDoc was a technology that defines an intermediate file format to support various EDI formats.Thus we have realized data exchange by converting from IDoc data formats to the ones used by business partners with external middleware or vice versa. Therefore, IDocs are still widely used in B2B scenarios such as ordering even today. IDoc technology has been gradually expanded from the conventional file-based technology, and has evolved to allow direct data export and import using RFC, SOAP, and plain HTTP. In particular, the technology that connects ABAP based SAP systems with RFC was called ALE (Application Link Enabling). Since we originally assumed a fixed-length data format, the data structure has some quirks. Nowadays it is often used in conjunction with SAP Process Integration or SAP Cloud Platform Integration because it basically requires format mapping.
Let's access to the SAP API Business Hub to find the information.
In the SAP API Business Hub, there is API information for various applications including Cloud LoB solutions such as SAP Concur and SAP SuccessFactors as well as SAP S/4HANA.
You can search API, check information, test, etc. on this site. However, SAP API Business Hub is basically developed for Cloud Solution, we only offer a limited information or functionalities for the On-Premise systems.
As an example, suppose you want to find an API that registers an order entry for SAP S/4HANA On-Premise.
First, there is S/4HANA Cloud and S/4HANA in SOLUTIONS on the left.
Since it is an On-Premise, I will select SAP S/4HANA for the time being.
Click the Details tab to display the screen below.
As you can see the note like below as of April 2020, the API group of SAP S/4HANA (On-Premise) is not listed in API Business Hub unfortunately.
Note: SAP S/4HANA APIs are not currently on the SAP API Business Hub but will be available in an upcoming release.
As of now, the PDF file called API for SAP S/4HANA is only a summary of where the API can be found on the S/4HANA On-Premise system. In addition, SAP Labs Japan is working to put the information for SAP S/4HANA On-Premise on API Business Hub along with the information of S/4HANA version.
Let's go back to the first page and check with S/4HANA Cloud.
S/4HANA Cloud here means S/4HANA Cloud ES (Essentials Edition = formerly Multi-Tenant Edition).
https://blogs.sap.com/2019/08/22/sap-s4hana-cloud-and-on-premise-deployment-options/
As a release cycle, SAP S/4HANA Cloud ES is updated quarterly with a new version. On the other hand, solutions based on S/4HANA On-Premise software (including SAP S/4HANA Cloud EX * and HEC) will be updated once a year.
Various new features, including new APIs, are first updated on the S/4HANA Cloud ES side, and S/4HANA On-Premise will usually incorporates those features in the newer release later. This is also true to the new APIs.
In general, S/4HANA On-Premise has a new version once a year, there will be a situation that an API is available in 1809 but not in 1709.
* S/4HANA Cloud EX: S/4HANA Cloud Extended Edition - formerly known as S/4HANA Cloud Single Tenant Edition (STE)
I want to register a sales order, so enter Sales Order and search.
You can see that many APIs end with service categories such as (A2A), (B2B), (A2X).
https://wiki.scn.sap.com/wiki/display/HOME/Abbreviations+in+SOA
https://help.sap.com/viewer/229e86fa75e842a8b4134353eb9ba99c/750%20SP17/en-US/9141bb5d52dd420a99ffe5...
Although it is technically possible to use the OData API for data exchange between systems, it is often the A2X category because it is easier to use directly from the UI compared to SOAP. There are many APIs that do not have any category.
Click Sales Order (A2X) on the tile on the above screen, and the screen below is displayed.
This API References tab allows you to view and test the API specifications.
Here, you can connect to your company's system and test it by pressing Configure Environments, but since API Business Hub basically assumes a cloud solution to be connected, the system would need to accessible via HTTP from the public Internet.
Usually On-Premise system is only accessible from the corporate network and we cannot use this feature in that case.
Here let's try to use the public sandbox system.
Press the Try out button.
Let's put 3 in $ top and get only 3 from the sandbox system.
Select to_Item and to_partner for $ expand and press Execute in order to display details of line items and business partners at the same time.
Certainly, the HTTP return code 200 (success) returned 3 results of the Sales Order.
Sales Order Items information is also included in to_item.
I was able to confirm that the data was the data for the order receipt I expected.
Also, since there is a POST, you can see that you can register data.
You can access information and documentation for this API on the Details tab.
Here, you can check the URL, authentication information, and associated Business Object information.
Click Business Documentation to display S/4HANA Cloud (ES) information.
Currently there is no direct link to the S/4HANA On-Premise documentation, so
Let's search for help.sap.com using the technical information API_SALES_ORDER_SRV .
First, search for On-Premise S/4HANA with the keyword S/4HANA.
On the next page, select the version you want to check (1909 in the figure below) and enter the keyword of the technical name (API_SALES_ORDER_SRV in the figure below).
After selecting the search contents and climbing up the tree, I came to the information of the Sales Order API in the 1909 version.
If you do the same thing for SAP S/4HANA 1709, you can find "Read Sale Order" because only read-API is available for 1709.
Let's try to looking for the API for creating accounting documents.
Search on S/4HANA Cloud in API Business Hub using the keyword Journal Entry.
There is currently no OData API for registering accounting slips, it seems that it is only the SOAP API.
There are two types, Synchronous and Asynchronous, so this time click the Synchronous one.
You can download the WSDL (Web Service Description Language-the file that defines the SOAP message metadata) here.
The linked help is for S/4HANA Cloud (ES), so I will check if it exists in On-Premise.
First of all, I tried to search by entering the technical name in Help of S/4HANA On-Premise, but unfortunately help did not appear.
Next time you search with the likely name + API, it seems to be available because it came somehow.
The fist one might be the right one.
To check if the API really meets our requirements, we also need to go into the actual S/4HANA system and check it.
Go to t-code /IWFND/MAINT_SERVICE to get the list of OData API.
If there is no corresponding service, add it from the Add Service button at the top.
From the Call Browser button at the bottom left, you can check with a browser if it is only a query system.
In order to try create/update document such as POST / PUT / PATCH, it is necessary to use SAP Gateway Client or an external tool such as Postman for the testing.
In the case of SOAP, you can check it from the Enterprise Services Browser tab of t-code SE80.
You can also check the movement with the test tool here.
If the OData API for create/update does not exist, it may be necessary to check if the corresponding BAPI exists.
In this case, you will go into the actual system and access the BAPI Explorer with the t-code BAPI.
In BAPI Explorer, BAPI can be searched in the form associated with Business Object.
The ALE scenarios are organized by what I looked for in the Online Help Library of ALE Business Processes. This mainly contains information on SAP ERP (SAP R/3) fellowship scenarios (such as master data distribution).
Type information of IDoc type can be confirmed on t-code WE60.
IDoc integration with other systems is also included in the content of SAP Cloud Platform Integration.
As we have seen, in SAP S/4HANA On-Premise, there are relatively new APIs such as OData and SOAP, as well as the API that have existed since the SAP R/3 era, BAPI and IDoc.
If you want to build a UI or application on SAP Cloud Platform to connect with S/4HANA, I would recommended to check if OData API is available first. As we will explain in a subsequent blog, OData API is consumable with a library called SAP Cloud SDK, it is very easy to use. And because OData API can be regarded as a JSON-based REST service, it is easy to consume from the UI as well as server side logic.
If the standard OData API does not exist, it is possible to develop custom OData API in SAP S/4HANA. But in that case, in order to update the SAP standard object, BAPI must be used in the ABAP logic inside of the ABAP logic.
SOAP APIs are generally used by server-side applications rather than the direct consumption from the UI. Since it is possible to generate SOAP Client (Stub) with WSDL, you can develop an application that runs on SAP Cloud Platform Cloud Foundry in Java etc. and send a SOAP message to the SAP S/4HANA OP system.
IDoc was originally developed for EDI and is intended for asynchronous data communication, so it is often used with SAP Cloud Platform Integration.
API-related information is listed in the SAP API Business Hub, but the API information on the S/4HANA On-Premise system is not there yet.. Therefore, it is required to get the information by using Online Help etc. at the moment, but we will update this blog as soon as API Business Hub is updated.
For now, I think it's a practical way to check the information of SAP S/4HANA Cloud (EX) for OData and SOAP and check if it can be applicable to On-Premise as well.
1.Introduction
This blog is the second part of the blog series "How to extend SAP S/4HANA with SAP Cloud Platform". I will explain how to find an API for SAP S/4HANA on-premise.
- Overview of extended development on SAP Cloud Platform
- How to find SAP S/4HANA API <<<< HERE
- How to use SAP S/4HANA API
- when API does not exist
- Event Integration with SAP S/4HANA
As mentioned in the previous blog , there are two types of S/4HANA Extensions: In-App extensibility and Side-by-Side extensibility. In the case of Side by Side Extensiblity, an application developed with Java, JavaScript (Node.js), Python, etc. runs on SAP Cloud Platform, and connects to S/4HANA via API (Application Programming Interface). Therefore, it is necessary to find out what kind of API exists in SAP S/4HANA and how to use it.
2. The types of SAP S/4HANA API
Currently the most common and latest APIs of SAP S/4HANA are based on OData or SOAP. Let's look at the characteristics of each API type one by one.
OData is a standard REST-based protocol and is officially called Open Data Protocol. Previously promoted mainly by Microsoft, it became the OASIS standard in 2014. Most APIs of SAP S/4HANA as of now are based on OData V2. Since it is a REST protocol, CRUD (Create, Read, Update, Delete) of each OData API supports HTTP POST, GET, PUT/PATCH, DELETE, while some Odata APIs are only for read-only. Most of the latest S/4HANA APIs are OData based ones, so it's a good idea to look for OData APIs first.
SOAP is a Web Service protocol that was popular in the 2000s and is still used today. Once it was heavily used as a core technology of SOA (Service Oriented Architecture), and there are many SOAP-based APIs in S/4HANA. It is the same as OData in that it is based on HTTPS, but it is necessary to have an XML container called SOAP Envelope in the HTTP Body, and to put the XML (SOAP Body) that is the content in it. In many cases, SOAP Client is generated with a metadata file called as WSDL (Web Service Description Language).
Most of the APIs existing in SAP API Business Hub introduced here are provided in OData or SOAP format.
BAPIs and IDocs are the legacy APIs that have long been used since the era of SAP R/3 and SAP ECC. These are not listed in SAP API Business Hub, and it is necessary to check them in the system of each S/4HANA and/or online help.
BAPI (abbreviation of Business Application Programming Interface) is a legacy API implemented in the form of functions called SAP Function Modules. It is possible to be called from outside using SAP's own protocol called RFC (Remote Function Call). If you want to call BAPI from Java, you can use the wrapper library called as JCo (Java Connector, pronounced as Jay-co) and you can use .Net Connector (= NCo) for .Net based apps . BAPI is logically defined as a method of Business Object * ( the objects such as sales order good receipts, material masters, etc. that are defined in S/4HANA such as documents and masters). * This Business Object is not relevant to BI Tools SAP Business Objects
IDoc is an abbreviation for Intermediate Document.
Originally, IDoc was a technology that defines an intermediate file format to support various EDI formats.Thus we have realized data exchange by converting from IDoc data formats to the ones used by business partners with external middleware or vice versa. Therefore, IDocs are still widely used in B2B scenarios such as ordering even today. IDoc technology has been gradually expanded from the conventional file-based technology, and has evolved to allow direct data export and import using RFC, SOAP, and plain HTTP. In particular, the technology that connects ABAP based SAP systems with RFC was called ALE (Application Link Enabling). Since we originally assumed a fixed-length data format, the data structure has some quirks. Nowadays it is often used in conjunction with SAP Process Integration or SAP Cloud Platform Integration because it basically requires format mapping.
3.Finding an OData API
Let's access to the SAP API Business Hub to find the information.
In the SAP API Business Hub, there is API information for various applications including Cloud LoB solutions such as SAP Concur and SAP SuccessFactors as well as SAP S/4HANA.
You can search API, check information, test, etc. on this site. However, SAP API Business Hub is basically developed for Cloud Solution, we only offer a limited information or functionalities for the On-Premise systems.
As an example, suppose you want to find an API that registers an order entry for SAP S/4HANA On-Premise.
First, there is S/4HANA Cloud and S/4HANA in SOLUTIONS on the left.
Since it is an On-Premise, I will select SAP S/4HANA for the time being.
Click the Details tab to display the screen below.
As you can see the note like below as of April 2020, the API group of SAP S/4HANA (On-Premise) is not listed in API Business Hub unfortunately.
Note: SAP S/4HANA APIs are not currently on the SAP API Business Hub but will be available in an upcoming release.
As of now, the PDF file called API for SAP S/4HANA is only a summary of where the API can be found on the S/4HANA On-Premise system. In addition, SAP Labs Japan is working to put the information for SAP S/4HANA On-Premise on API Business Hub along with the information of S/4HANA version.
Let's go back to the first page and check with S/4HANA Cloud.
S/4HANA Cloud here means S/4HANA Cloud ES (Essentials Edition = formerly Multi-Tenant Edition).
https://blogs.sap.com/2019/08/22/sap-s4hana-cloud-and-on-premise-deployment-options/
As a release cycle, SAP S/4HANA Cloud ES is updated quarterly with a new version. On the other hand, solutions based on S/4HANA On-Premise software (including SAP S/4HANA Cloud EX * and HEC) will be updated once a year.
Various new features, including new APIs, are first updated on the S/4HANA Cloud ES side, and S/4HANA On-Premise will usually incorporates those features in the newer release later. This is also true to the new APIs.
In general, S/4HANA On-Premise has a new version once a year, there will be a situation that an API is available in 1809 but not in 1709.
* S/4HANA Cloud EX: S/4HANA Cloud Extended Edition - formerly known as S/4HANA Cloud Single Tenant Edition (STE)
I want to register a sales order, so enter Sales Order and search.
You can see that many APIs end with service categories such as (A2A), (B2B), (A2X).
- A2A (Application to Application): Exchange data from system to system within a company
- B2B (Business to Business): Exchange data from one system to another
- A2X (Application to X user or Application to Cross Application): API to get the application to be used via UI etc.
https://wiki.scn.sap.com/wiki/display/HOME/Abbreviations+in+SOA
https://help.sap.com/viewer/229e86fa75e842a8b4134353eb9ba99c/750%20SP17/en-US/9141bb5d52dd420a99ffe5...
Although it is technically possible to use the OData API for data exchange between systems, it is often the A2X category because it is easier to use directly from the UI compared to SOAP. There are many APIs that do not have any category.
Click Sales Order (A2X) on the tile on the above screen, and the screen below is displayed.
This API References tab allows you to view and test the API specifications.
Here, you can connect to your company's system and test it by pressing Configure Environments, but since API Business Hub basically assumes a cloud solution to be connected, the system would need to accessible via HTTP from the public Internet.
Usually On-Premise system is only accessible from the corporate network and we cannot use this feature in that case.
Here let's try to use the public sandbox system.
Press the Try out button.
Let's put 3 in $ top and get only 3 from the sandbox system.
Select to_Item and to_partner for $ expand and press Execute in order to display details of line items and business partners at the same time.
Certainly, the HTTP return code 200 (success) returned 3 results of the Sales Order.
Sales Order Items information is also included in to_item.
I was able to confirm that the data was the data for the order receipt I expected.
Also, since there is a POST, you can see that you can register data.
You can access information and documentation for this API on the Details tab.
Here, you can check the URL, authentication information, and associated Business Object information.
Click Business Documentation to display S/4HANA Cloud (ES) information.
Currently there is no direct link to the S/4HANA On-Premise documentation, so
Let's search for help.sap.com using the technical information API_SALES_ORDER_SRV .
First, search for On-Premise S/4HANA with the keyword S/4HANA.
On the next page, select the version you want to check (1909 in the figure below) and enter the keyword of the technical name (API_SALES_ORDER_SRV in the figure below).
After selecting the search contents and climbing up the tree, I came to the information of the Sales Order API in the 1909 version.
If you do the same thing for SAP S/4HANA 1709, you can find "Read Sale Order" because only read-API is available for 1709.
4. Finding a SOAP API
Let's try to looking for the API for creating accounting documents.
Search on S/4HANA Cloud in API Business Hub using the keyword Journal Entry.
There is currently no OData API for registering accounting slips, it seems that it is only the SOAP API.
There are two types, Synchronous and Asynchronous, so this time click the Synchronous one.
You can download the WSDL (Web Service Description Language-the file that defines the SOAP message metadata) here.
The linked help is for S/4HANA Cloud (ES), so I will check if it exists in On-Premise.
First of all, I tried to search by entering the technical name in Help of S/4HANA On-Premise, but unfortunately help did not appear.
Next time you search with the likely name + API, it seems to be available because it came somehow.
The fist one might be the right one.
5. Test OData and SOAP with the actual SAP S/4HANA OP system
To check if the API really meets our requirements, we also need to go into the actual S/4HANA system and check it.
Go to t-code /IWFND/MAINT_SERVICE to get the list of OData API.
If there is no corresponding service, add it from the Add Service button at the top.
From the Call Browser button at the bottom left, you can check with a browser if it is only a query system.
In order to try create/update document such as POST / PUT / PATCH, it is necessary to use SAP Gateway Client or an external tool such as Postman for the testing.
In the case of SOAP, you can check it from the Enterprise Services Browser tab of t-code SE80.
You can also check the movement with the test tool here.
6. Finding BAPI or IDoc search and test it
Check BAPI
If the OData API for create/update does not exist, it may be necessary to check if the corresponding BAPI exists.
In this case, you will go into the actual system and access the BAPI Explorer with the t-code BAPI.
In BAPI Explorer, BAPI can be searched in the form associated with Business Object.
For IDoc
The ALE scenarios are organized by what I looked for in the Online Help Library of ALE Business Processes. This mainly contains information on SAP ERP (SAP R/3) fellowship scenarios (such as master data distribution).
Type information of IDoc type can be confirmed on t-code WE60.
IDoc integration with other systems is also included in the content of SAP Cloud Platform Integration.
7. Conclusion
As we have seen, in SAP S/4HANA On-Premise, there are relatively new APIs such as OData and SOAP, as well as the API that have existed since the SAP R/3 era, BAPI and IDoc.
If you want to build a UI or application on SAP Cloud Platform to connect with S/4HANA, I would recommended to check if OData API is available first. As we will explain in a subsequent blog, OData API is consumable with a library called SAP Cloud SDK, it is very easy to use. And because OData API can be regarded as a JSON-based REST service, it is easy to consume from the UI as well as server side logic.
If the standard OData API does not exist, it is possible to develop custom OData API in SAP S/4HANA. But in that case, in order to update the SAP standard object, BAPI must be used in the ABAP logic inside of the ABAP logic.
SOAP APIs are generally used by server-side applications rather than the direct consumption from the UI. Since it is possible to generate SOAP Client (Stub) with WSDL, you can develop an application that runs on SAP Cloud Platform Cloud Foundry in Java etc. and send a SOAP message to the SAP S/4HANA OP system.
IDoc was originally developed for EDI and is intended for asynchronous data communication, so it is often used with SAP Cloud Platform Integration.
API-related information is listed in the SAP API Business Hub, but the API information on the S/4HANA On-Premise system is not there yet.. Therefore, it is required to get the information by using Online Help etc. at the moment, but we will update this blog as soon as API Business Hub is updated.
For now, I think it's a practical way to check the information of SAP S/4HANA Cloud (EX) for OData and SOAP and check if it can be applicable to On-Premise as well.
7 Comments
