Explaining Open Data Protocol (OData)

One important aspect of the architecture of the World Wide Web is the use of abstract interfaces for component communication. These abstract interfaces are presented as connectors. A client and a server each use a connector component. There is a contract between both connectors that defines the application protocol. It defines the documents, their format, and the behavior. Any protocol can be chosen. By using the connector concept, both client and server are largely independent and exchangeable. Each connector translates the documents exchanged on the communication channel to the internal representations both on the server and on the client side, and vice versa.

The OData protocol defines such a contract by specifying a uniform protocol that has the necessary qualities. For instance, a connector attached to an SAP back-end system translates between ABAP APIs and OData entities. SAP Gateway is such a connector.

On the other side, a client connector translates between OData entities and the APIs of the consumer platform. The connector is specified here. As a consequence, any client platform with libraries supporting the contracted OData format can communicate with any server supporting the same contract.

OData follows the Representational State Transfer (REST) architecture design paradigm in the sense that the protocol transfers representations of the state of resources. The term resource denotes data that is addressable and accessible. The standard address representation or resource is the Uniform Resource Identifier (URI). A client requests a resource from a server by sending a request to a URI. The server processes the request by translating the URI to internal address data to access or manipulate the data, and then assemble the response.

OData is an open standard originally developed by Microsoft but now managed by the Oasis Organization. It is based on the Atom Publishing and Atom Syndication standards, which, in turn, are based on XML (Extensible Markup Language) and HTTP(S) (HyperText Transfer Protocol (Secure)). JSON (JavaScript Object Notation) is an alternative to XML to structure data.

The objective of the OData protocol is to provide a vendor-neutral, web-based API that fully complies with the design principles of Representational State Transfer (REST). OData provides database-like access to server-side resources. In this context, OData is also called ODBC for the Web.

OData is also extensible. This enables SAP to supplement the data types used by OData with extra information from the ABAP Data Dictionary. Another example is metadata-driven development for Web and mobile like SAP Fiori elements.

OData is available in version 2 (V2), version 3 (V3), and version 4 (V4). The versions are built on each other extending the previous version by adding new features. The majority of OData services are based on V2. SAP Gateway supports OData V2 since AS ABAP 7.00 and OData V4 since AS ABAP 7.50. OData V3 was skipped in SAP Gateway and is therefore not supported.

In current real-life applications, JSON (JavaScript Object Notation) is used instead of Atom and XML for structuring data. It needs considerably less meta-information, which reduces the amount of data transferred greatly. Atom and XML, in contrast, are used precisely because of the extensive meta-information when it comes to development.

Because OData uses the HTTP protocol, any Web browser can be used to start exploring OData. Adding the query option $format=xml to the URI (Unified Resource Identifier) let the OData service provide the data as an Atom XML file. Most Web browsers display the Atom Publishing Protocol (APP) as XML-tree because of the missing style information – but this is perfectly fine. There is even some coloring available to better distinguish the different parts in the XML file.

Adding the query option $format=json to the URI let the OData service provide the data as a JSON file. By default, JSON does not display properly in any browser. If you want to explore the OData protocol using JSON, you may install a JSON-viewer plug-in like JSONView.

For SAP Gateway services, SAP provides the debugging query option sap-ds-debug=true. This query option renders the OData response in an HTML format that can be displayed by any browser. The Atom or JSON file is embedded in the HTML page and can therefore be visualized like any other content in an HTML page. It also makes the relative links active so that you can navigate to the resource by just clicking the link. Finally, the developer can access various information in additional screens via buttons above the response.

The additional screens provide more details about the request and response and the environment of the call:

• There are more details about the Request available like the used URI options or Web browser.
• The Response shows the HTTP status code and cache information.
• Server information like protocol version or IP address can be obtained.
• A small Runtime analysis provides a call stack of the called ABAP methods.

In case of an error, an additional screen providing a Stacktrace gets available. If the error information in the Web browser is not very useful, because it is a general 500 internal server HTTP error, you can use the debugging query option to further investigate such an error. In the stacktrace, you can see useful context information and the location where the original error occurred.

The entities of an OData service are defined in an Entity Data Model (EDM). Entity types define properties and navigations to other entity types. These associations define relation constraints based on key properties of the entity types. A navigation property is then used to actively navigate between entities during runtime. For every entity type, at least one entity set is defined. These are shown in the service document and used to request data from the OData service.

By adding the OData option $metadata to the service root URI, the metadata document of the service is shown. The whole EDM is defined here and available at runtime. Application developers and all the wizards in development environments consuming OData services create their applications based on this information.

The core of the EDM is the entity-relationship model. The entity-relationship model has existed for over 30 years and differs from the more familiar relational model because associations and entities are both first-class concepts. An OData service metadata document describes its data in EDM terms by using an XML language for describing models, known as the conceptual schema definition language (CSDL).

The purpose of the service metadata document is to enable clients to discover the structure of an OData service, the structure of its resources, the known links between resources, and the service operations exposed. A service metadata document describes the EDM for a given service.

Entities are instances of entity types, which are richly structured records with a key. The structure of an entity type is provided by its properties. An entity key is formed from a subset of the properties of the entity type. The key (for example ProductD) is a fundamental concept used to uniquely identify and persist entity instances and to allow entity instances to participate in associations. The key of an entity is defined by one or many properties. Entities can be addressed individually by means of key values, or as collections by means of query options.

Because of the extensibility of OData, SAP supplemented the properties with extra information from the ABAP implementation. This includes translatable labels, data semantics, and operation indicators. Application developers can make use of them to dynamically adapt the UI based on this information. For example, an input field can be write-enabled if it is allowed that the property is updatable.

Beside the name, a property of an entity type must declare a type. In most cases, this is a primitive type like string or decimal. An entity type consisting only of properties based on primitive types is comparable to the definition of a data base table including a key and associations to other entities.

Beside primitive types, properties can also be declared based on complex types. A complex type is a collection of properties defined in the same way as the properties in entity types. But there is no key or any association possible. A complex type is comparable with a structure in ABAP. Therefore, an entity type having parameters based on complex types is comparable with a deep structure.

In OData V4, it is also possible to define enumeration types. These work like enumerations in other areas: it is a complete ordered listing of items in a collection. For example, by declaring a property based on an enumeration, a filter in an OData request can check the validity of the data based on the items of the enumeration.

An EDM describes the organization and relationship of the data resources that are modeled as entity types within a particular business scenario. Entity sets are collections of entities, which are instances of entity types and can be accessed as follows:

• http://<host>:<port>/<ServiceRoot>/BusinessPartnerSet
• http://<host>:<port>/<ServiceRoot>/People

Entities are grouped into entity sets. For example, the People entity set is a set of Person instances. All entities of one entity set are of the same entity type.

In OData V4, it is also possible to define an entity type as a singleton, for example, the Person entity type as the Me singleton. A singleton is a specialization of an entity set just having one entity.

In OData V2, an association is a named relationship between two entity types. Every association includes two association ends, which specify the entity types that are related, and the cardinality rules for each end of the association. Associations between two entity types can be compared to foreign key relationships between two database tables.

Entity types may include one or more navigation properties. The navigation property derives its name from the fact that it allows navigation from one entity to others. A navigation property is tied to an association and allows navigation from one end of an association, the entity type that declares the navigation property, to the other related end, which can be anything from 0 or more related entities.

For a navigation to take place, it is also needed to associate the entity sets instantiating the entity types. This is the task of the association set. In that way, it is possible to associate a supplier with a customer both declared as business partners. For example, the BusinessPartner entity type has a navigation property named ToProducts. The navigation property makes it possible to navigate from a business partner instance to all the products of that business partner. If the business partner would be further distinguished in supplier and customer, it makes a difference who sells or buys the product.

In OData V4, the navigation was simplified. There are still navigation properties in entity types, which are called the same way in OData requests like before. But instead of referring to an association, the navigation property itself defines the relationship to another entity type.

With the association now missing, the association set got replaced by the navigation property binding. Such a binding is defined as part of the entity set, which is instantiating the entity type, and matches the navigation property of the entity type. The purpose of the binding is, like before the association, set to associate the entity sets in a navigation. So instead of three elements in OData V2, a navigation definition in OData V4 consists of just two elements.

Functions and actions are used to perform activities in an OData service that are too complicated or performance intensive to provide them in the usual manner. For example, to confirm a sales order sounds simple on the one hand. But on the other hand, an OData service consumer, the client developer, does not have the insight in the internal handling of sales orders of the service provider. Which property of the entity must be set to which value? Are there any dependent processes to be addressed? To answer this question, the service developer can provide a function implementing all details in the service provider but only asking for the sales order ID to run it.

In addition to this separation, a function (import) is always reading and returning data. The task to change data in the service provider is taken over by the action (import). It can also define parameters based on primitive types but cannot return any data. This is comparable to a generic action in a UI, in contrast to a function calculating something and returning the result.

There are many elements in the EDM connected in many ways to each other. Some are only valid for a certain OData version, but the most important ones like entity type or entity set are the same in all versions. Singleton and enumeration types are nice additions in V4 and even the separation of function imports in actions and functions is mainly an enhancement but not an incompatible change. Only the navigation really differs between V2 and V4 in its definition. Luckily, calling a navigation or also a function import is done the same way in every version.