This blog is meant as an introduction of a series of blogs in which I will explain the use of the new SAP Gateway V4 framework.
It is meant for those readers that must create OData V4 series now and that cannot wait until an end-2-end support for OData V4 will be available through the new ABAP programming model.
Before starting code based OData V4 development you should check my blog OData service development options where I outline in more detail what the recommended options for OData development are right now.
13.12.2017 - added link to the first how to guide and the blog that explains the OData service devlopment options in more detail
The main paradigm of the OData V4 paradigm is the reduction of data. This reduction is achieved through a more powerful query language and a new optimized JSON protocol. At the same time it is possible to leverage richter metadata as compared to OData V2.
New JSON format
The OData V4 protocol comes with a very lean JSON procol. The response payload now basically only contains name value pairs. The metadata has been reduced to a a single line
"@odata.context" : "$metadata#SalesOrder/$entity"
as opposed to the more richer metadata information in the V2 response payload, both highlighted in blue in the following figure.
Cross service references
Cross service navigation enables inter communication of services. With this, navigation properties of entities of one service can reach entities of another service in a service group. With the support of cross service navigation several requirements of SAP Fiori like applications can be addressed.
1.) The rich metadata can be leveraged but at the same time not the complete data model has to be loaded at startup time of an application. There is rather the option to have a lazy loading of parts of a service model on demand.
2.) Services can be reused more easily since services can be partioned without the loss of navigation.
Examples of such services that can be reused in various SAP Fiori applications are Users, Attachments, Conditions, Addresses, …
Cross service references are only possible within one service group.
or it is possible to find all sales orders where every item has a price greater than $100
…/SalesOrders?$filter = _Item/all(d:d/Price ge 100)
Filter on expanded result sets
New in OData V4 is the option for filtering on each level of an expanded enttiy set. In the following figure you see a request that
reads all business partners that are located in 'Walldorf'
reads all sales orders of those business partners where the gross amount exceeds 1100 Euro
reads only those items that contain the product HT-1041.
What's new in the framework?
Advanced, intermediate and basic interfaces
The API that is used to develop OData V4 services has significantly changed compared to the API that is used to develop OData V2 services.
When you implement the methods of the basic interface you will get a working OData V4 service that will satisfy most requests. Complex requests such as $expand are then handled by the framework that will call the methods for the basic interface in the correct order.
The mplementation of the intermediate or advanced interface should however also be taken into account if your service implementation would be able to handle specific requests such as specific $expand or navigation calls more efficient than by calling the methods of the basic interface recursively.
Methods provide basic functionality
(Create, Update, Delete, Navigation, …)
When being implemented à Working OData service supporting most requests
Medium complex functionality
eTag handling, PATCH, $expand
Contains generic calls to other (especially the basic) interfaces
Always called first by the framework
Contains generic calls to the other (especially the basic) interfaces
Will for example be overwritten by the new RESTful ABAP Programming model (planned)
$batch. Generic $batch and changeset
Transaction and lifecycle handling
io_request and io_response
All interface methods have an import parameter called io_request. It can be used to retrieve all information you need to handle the request in your service implemenation.
A UPDATE_ENTITY method for example will have the following methods
GET_BUSI_DATA to retrieve entity data from the request, for example the payload of the incoming request.
GET_ENTITY_SET to retrieve the entity set of the processed entity. So we can switch to entity set specific methods
The corresponding parameter ip_response is used to return business data to the SAP Gateway framework and to tell the framework which processing steps the service implementation has handled iself (see todo and done flags below).
Generic framework support - example $expand
As already mentioned you will get a working OData V4 service by only implementing the methods of the basic interface.If a client calls the following URL:
the SAP Gateway framework will call the following basic methods in your service implementation:
This method will read the data of the sales order header
This method will read the key fields of the items that can be used by the READ_ENTITY_LIST method as a $filter statement
With OData V4 now query options are supported on all levels of an $expand statement.
ToDo and Done-Flags
The SAP Gateway V4 framework has introduced so called ToDo-Flags which provide a hint for the application developer what his implemenations has to do. Depending ont the query options that have been used in the request you will get simple list with boolean values for the following flags:
Done-Flags confirm that the response fits to the request. They allow the application developer to inform the framework to handle feature generically e.g., $top, $skip, and $select. Using such flags also allows an implementation tobe compatible in the future. Instead of a wrong result an exception will be raised if a done flag is not set.
The list of todo and done flags will vary depending on the method which is called. (READ; READ_LIST, CREATE, ...)
For a simple GET request with a $filter query option:
…/SalesOrder?$filter=Customer eq ‚SAP‘
a service implementation would have to look like as follows.
At the beginning of our service implementation we have to check whether we have to handle the filter option. For this we call the method io_request->get_todos. Then we have to check whether the flag ls_todo_list-process-filter is set. If yes, the filter string is requested via the method io_request->get_filter_osql_where_clause and the flag that we have handled the filter query option is set in the structure ls_done_list. This information is at the end sent back to the framework via the method io_response->set_is_done that takes the done-list as a parameter.
io_request->get_todos( importing es_todo_list = ls_todo_list ).
if ls_todo_list-process-filter = abap_true.
io_request->get_filter_osql_where_clause( importing ev_osql_where_clause = lv_where_clause ).
ls_done_list-filter = abap_true.
" Report list of request options handled by application
io_response->set_is_done( ls_done_list ).