Exploring the Architecture of the ABAP RESTful Application Programming Model

In this blog post, we’ll go into detail about the main architecture-relevant concepts of the ABAP RESTful application programming model.

This includes the technical components in which a RAP application is embedded at runtime.

Transaction Model

The RAP transaction model distinguishes between two phases in the processing of operations on business objects:

1. During the interaction phase, operations are performed on a business object instance (e.g., a position is created or changed). As a result of these operations, instances of the respective CDS entities are stored in the transaction buffer.
2. The subsequent save sequence is triggered by a commit. The state of the transaction buffer is persistently written to the database. The state of the transaction buffer isn’t kept across multiple requests, as this would violate a key REST principle. The CDS entity instances that are stored in the transaction buffer, which have been created, modified, or deleted (modify), can be considered a logical unit of work (LUW) within the SAP system. As part of the save sequence, the LUW is persistently written to the database within a database LUW.

The draft handling in the ABAP RESTful application programming model allows to temporarily store the state of the transaction buffer with inconsistent application data persistently on the database. This enables you to distribute the interaction phase across multiple standalone requests or user sessions without violating the REST principles of stateless communication. Users can continue their work at a later point in time, regardless of the terminal device. The draft handling functionality is fully implemented by the RAP runtime.

Basically, the ABAP RESTful application programming model doesn’t preclude the implementation of a stateful application. The RAP transaction model technically includes an area (the transaction buffer) where the application state can be stored on the server side. However, in this book we’ll focus on REST-based applications.

Implementation Types

The ABAP RESTful application programming model includes the concept of the implementation type, which you use to specify who provides the implementation of reading functionality (query) and transactional or writing functionality (behavior). There are two implementation types: managed and unmanaged. In the managed case, the programming model provides the desired functionality; in the unmanaged case, the application must do this by itself.

The technical implementation of read and write access or the behavior of a business object is handled by the business object provider. When implementing the business object, we distinguish between the use of the managed scenario and the unmanaged scenario:

Managed Scenario

In the managed scenario, you use a ready-made implementation of the business object provided by the ABAP RESTful application programming model, the managed business object provider. It implements the standard CRUD operations for creating (create), reading (read), updating (update), and deleting (delete) instances of the respective CDS entity during the interaction phase and the save sequence. This is also accompanied by the handling of the transaction buffer.

When using the managed scenario, an already executable business object that supports CRUD operations is available to you without any programming effort on your part. Optionally, you can add more logic to the save sequence (additional save) or implement it yourself (unmanaged save).

Unmanaged Scenario

In the unmanaged scenario, you can implement the standard functionality of a business object by yourself. This involves the interaction phase with the transaction buffer and the save sequence. This gives you the option of integrating the API of an existing application and wrapping it with RAP resources. This scenario is therefore often used for brownfield development.

In addition to the use cases that can be implemented by these implementation types, there are always very specific business requirements (e.g., the validation of a certain data constellation or the calculation of certain values of a business object instance). In these cases, the business object provider can’t provide an implementation. However, in both the managed and unmanaged scenarios, you can implement the respective business logic yourself.

Read accesses are referred to as queries in the ABAP RESTful application programming model. They can be implemented without transactional behavior or associated write accesses. A managed implementation of this type of read access is called a managed query, and an unmanaged implementation is called an unmanaged query. Via the managed query, the programming model provides the standard functions for reading business data from the underlying database. This also includes, for example, functions for sorting, filtering, or aggregating the read data. If you implement an unmanaged query, you can implement these functions yourself and thus have the option of including any data source in the programming model (e.g., via remote call of APIs), or bridging differences between the data model of the data source and that of the business object in the ABAP RESTful application programming model.

Entity Manipulation Language

The entity manipulation language (EML) is a standardized, type-safe API used to access the data and functionality of a business object. It’s an integral part of the ABAP language scope. Using EML, you can access instances of a business object in write mode (via the ABAP statement MODIFY ENTITIES), but you can also read individual instances from the transaction buffer (via READ ENTITIES).

EML plays a major role within the ABAP RESTful application programming Use cases model in the following use cases:

• Implementing the behavior of a business object: You can use EML statements to implement the behavior of a business object in ABAP. In this case, your application assumes the role of a business object provider.
• Performing operations on a business object: You need EML statements if you program an ABAP application that accesses the functionality of a business object as a consumer (i.e., assumes the role of the business object consumer). It’s also possible to use EML in the context of unit tests to check the functionality of a business object in your application.

When you use EML within the business object provider, for example, to read data for validation, you also use the EML in the business object consumer role. You use it to read data about the business object from the transaction buffer to validate it, bypassing authorization checks, for example, because the access is IN LOCAL MODE. You thus consume the read or write functionality of your own business object. In addition to read and write operations, you can also use EML to define transaction boundaries (COMMIT and ROLLBACK behavior) and trigger the save sequence.

Technical Context of Applications and Runtime Environment

In the figure below you can see the technical context in which an application created with the ABAP RESTful application programming model is embedded. Here, you will gain an idea of the technical paths and protocols that can be used to access the data and services of a RAP application. A RAP application uses the SAP HANA database to persist application data. CDS custom entities allow you to connect an external system or other data source through synchronous communication using a query programmed, specifically in ABAP.

Although you don’t need to understand the specific technical components of the ABAP RESTful application programming model in detail for the RAP runtime to process RAP requests, it does help to know the essential building blocks involved in this process. It not only improves the general understanding of the programming model, but can also be very useful with regard to troubleshooting.

In the next figure, you can see the technical components involved in processing a RAP request.

This type of request can be, for example, the creation of a purchase order via the CRUD operation create. A request can originate from an external application (e.g., a SAP Fiori interface or a web API consumer) using the OData protocol, or it can be made as a local call (that is, internal to the system) via the EML.

In the following bullet points we’ll describe the individual components:

• SAP Gateway: SAP Gateway implements the OData protocol and serves external applications as an entry point into the respective application. To do this, SAP Gateway receives the OData request and forwards it to the orchestration framework for generic processing.
• Orchestration framework: The orchestration framework maps the OData request to a RAP request and evaluates it generically. The orchestration framework is also known as the service adaptation and description language (SADL) framework. A read access is forwarded to the appropriate query implementation, a write and, thus, transactional access is processed via the business object framework. The orchestration framework thus forms the transactional bracket around the RAP request and is responsible, for example, for requesting locks, ETag handling, and commit and rollback behavior. For read and write accesses, the orchestration framework determines whether the methods of a managed or unmanaged implementation need to be invoked.
• Business Object Framework: The business object framework controls the processing of operations on a business object. It ensures that during the interaction phase and save sequence, the intended methods of the business object provider API are called in the managed or unmanaged behavior implementation. While in an OData request, the orchestration framework takes over the control of the interaction phase and the save sequence, you have the possibility via your ABAP and the EML code to control which operations run within the interaction phase and when the save sequence will be triggered.

Using SAP Gateway in the Background

The ABAP RESTful application programming model uses OData by default to expose access to the application's functionality, using SAP Gateway as the framework and runtime environment. For you, however, SAP Gateway doesn’t appear during the development of RAP applications. The programming model generates the gateway artifacts in the background so that they can accept an OData request for the programming model at runtime.

This also means that you can’t use the ABAP RESTful application programming model to access the gateway development capabilities (that is, Transaction SEGW, and the data and model provider implementation), even if they are technically available on the respective ABAP application server. Such direct access would make the programming model dependent on a particular technology, which is contrary to the architectural goals of the programming model.

Learn ABAP OOP in Our Upcoming Rheinwerk Course!

Enhance your ABAP skills with object-oriented programming! Create classes, implement polymorphism, and more. Use exceptions for error handling and write unit tests to improve your code. Learn about key design patterns and apply your ABAP Objects knowledge to the ALV object model (SAP List Viewer). This upcoming course in January is live on the web and will teach you all you need to know about these topics. Click on the banner below to learn more and order your ticket.

Editor’s note: This post has been adapted from a section of the book ABAP RESTful Application Programming Model: The Comprehensive Guide by Lutz Baumbusch, Matthias Jäger, and Michael Lensch.