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.
