Purpose
Application developers who are using BAPIs in their application programs must be able to rely on the fact that the BAPI's interface is not going to change. As a result of this, once a BAPI is released and frozen, it must fulfill certain requirements as to the stability of its interface.
If you continue developing your BAPI after you have released and frozen it, you need to ensure that any syntax changes or changes to the contents or functionality of the BAPI are upward and downward compatible. Examples of syntax changes are changes to parameter names, or changes to the type or length of a domain.
Whereas the compatibility of syntax changes is automatically checked by the ABAP
Dictionary, the compatibility of changes to the contents or functional scope of a BAPI can only be safeguarded by the person developing the BAPI.
Note
Enhancements to BAPIs only take effect when you have defined the changes in the BOR, that is, changes have been saved and generated. The BOR also provides version control for your BAPIs.
You can differentiate between compatible and incompatible BAPI enhancements:
Compatible Interface Enhancements
Compatible interface enhancements are modifications to a BAPI which do not compromise the BAPI's upward or downward compatibility. Applications which access the BAPI are not
affected by compatible interface enhancements.
Compatible interface enhancements are:
• New optional parameters
A parameter is considered to be optional if it can be left out completely in a BAPI call.
Example
A new parameter is added to the BAPI SalesOrder.GetList which can be used as an additional selection criteria for selecting sales orders in the R/3 System.
• New optional fields, if these are added to the end of a structure
A field is considered to be optional if it can be left out completely in a BAPI call.
Example
An additional input field for the applicant's educational background is added to the BAPI Applicant.CreateFromData.
Incompatible Interface Enhancements
Changes to the contents or functionality of a BAPI often result in the introduction of new parameters without which the interface can no longer function. Often, these changes also cause existing parameters to lose their original meaning. Such modifications are considered to be incompatible, because they no longer enable the BAPI to be upward or downward
compatible.
Incompatible interface enhancements are:
• Changes to the field length
• Changes to the field type
• Adding new mandatory fields or mandatory parameters
Process Flow
When continuing the development of your BAPI, you should attempt to make compatible changes in order to limit the impact of your modifications on existing programs which use the BAPI. When adding a new import parameter, consider whether the interface would function without the parameter. If so, the new parameter can be added as a compatible interface enhancement. Otherwise you will have to make an incompatible interface enhancement, as described in this section.
Procedure With Incompatible Interface Changes
If it is necessary to make an incompatible change to your BAPI, you must not make this change to the existing BAPI. Instead, create an additional BAPI (or more, if required). Give the new BAPI the same name as the existing BAPI and add a number at the end of the name.
This number can then be incremented should further enhancements become necessary.
Example
A number of incompatible changes must be made to the BAPI
SalesOrder.CreateFromData. To implement these changes, a new BAPI,
SalesOrder.CreateFromData1, is created, in order to maintain the interface integrity of the existing BAPI SalesOrder.CreateFromData.
If additional incompatible modifications must be made to the BAPI at a later date, yet another BAPI, SalesOrder.CreateFromData2, must be created.
Do not remove the original BAPI from the Business Object Repository (BOR) once it has been superseded by an additional BAPI. Instead, you first identify this BAPI as expired and continue its support in the release in which you have introduced the new BAPI as well as in the release subsequent to that. During this time the original BAPI must remain fully functional and
executable.
The graphic below illustrates the expiry phase of a BAPI.
BAPI Expiry Phase
The following tasks are required when a BAPI has expired:
• Identify the status of the original BAPI as 'expired' in the BOR.
To do so, select the relevant SAP Business Object in the Business Object Builder and open the node Methods. Position the cursor on the BAPI and select Edit → Change status to → Expired.
• In the BOR, document which method or methods are to be used as alternatives to the expiring BAPI.
• Provide release notes during the entire retirement phase of the BAPI to inform your users about the changes.
Checks in the ABAP Dictionary
Syntax changes to a BAPI are automatically checked against the ABAP Dictionary:
• Incompatible changes to data elements, domains or structures that are being used by a BAPI that has been released are rejected by the ABAP Dictionary.
• Compatible changes or changes to data elements, domains or structures of a BAPI that has not been released are accepted by the ABAP Dictionary.
This prevents unintentional and erroneous modifications to BAPI structures.