The new release of the SAP Mobile Platform emphasizes the use of Open Data (OData) Protocol/services for exposing SAP data consumed by mobile applications. The OData approach was used for online applications. However, from SAP Mobile Platform 3.0 on, there is now support for offline applications. In addition, it can be used in the development of both hybrid as well as native applications. This makes OData an important topic for SAP mobility development.

The aim of this article is to give you an understanding of the OData Protocol and what you need to know about OData before starting mobile application development in an SAP system. I use the Firefox browser and the Representational State Transfer (REST) Client Add-on for illustrating Create, Read, Update, and Delete (CRUD) operations. Throughout the article, examples are included from the products and categories collections exposed at the sample services on the OData.org web site.

OData Backgrounder

OData Protocol allows RESTful access to resources in the form of a service via CRUD operations through a web address. It is based on HTTP, XML, and Atom.

An OData service uses the Entity Data Model (EDM) as the underlying data model. Within the EDM, you may have a number of entities that are linked together via associations. An entity can be defined as an instance of entity type; the entire set of these entities forms the entity set. An entity type represents the business object for a given scenario and can consist of a number of properties. Each entity type has a key based on one or more entity properties. For example, you have an entity type Category that has properties CategoryID, CategoryName, and Description, from which the CategoryID is the key property. Each entity can support CRUD operations. For example, you can display all categories or a particular category, create new categories, update the description of a particular category, or delete a given category.

There can be links or associations between two entity types. In addition to the other properties, an entity may have a special property known as a Navigation Property representing the link or association to another entity type. Via Navigation Properties, OData allows dynamic navigation between entities. For example, within the Category entity type, a navigation property called Products lets you link each Category entry with a collection of products (an example of this is in the upcoming section).

Service Document and Metadata Document

Two important documents exist for every OData service: the service document and the metadata document. I show how to access these documents via Uniform Resource Identifiers (URIs).

Each service has a service root URI. For example, say you have a Northwind OData service at the URI

https://services.odata.org/V2/Northwind/Northwind.svc. When you write the root URI in the browser or in a RESTClient using the GET method, it returns the service document listing the entity collections that are exposed by the service.

Figure 1

Service document of a sample Northwind service

To view this document, use /$metadata at the end of the service root URI. For example, for the Northwind service, the metadata URI is https://services.odata.org/V2/Northwind/Northwind.svc/$metadata. The returned EDMX document looks like the one shown in Figure 2 (partial view).

Figure 2

Metadata document of Northwind service

In the case of service and metadata document retrievals, execute a GET HTTP request. As you can see, the Categories collection related to the Entity type Category has a number of Properties, namely CategoryID, CategoryName, and Description. The CategoryID is the key property of the Category entity type. There is also a NavigationProperty Products linking Products and Categories.

The EDMX document tells you more about the types and length of the properties involved. Some of the supported types are shown in Table 1.

http:/services.odata.org/V2/Northwind/Northwind.svc/Categories
|----------------------Service Root URI-------------|--Resource Path-----|

If you like to view all categories having the CategoryID equal to 1, the corresponding URI looks like the one shown in Figure 4.

http:/services.odata.org/V2/Northwind/Northwind.svc/Categories(1)
|----------------------Service Root URI------------|--Resource Path-----|

Likewise, if you need to have all products pertaining to the Category 1, use the resource path shown in Figure 5.

http:/services.odata.org/V2/Northwind/Northwind.svc/Categories(1)/Products
|----------------------Service Root URI-----------|-----Resource Path-----|

The service root URI and the resource path can be supplied with further query options. The query option allows you to control the amount (or order) of returned data or to get further information on the specified resource. Figure 6 is an example.

http:/services.odata.org/V2/Northwind/Northwind.svc/Categories(1)/Products?$inlinecount=allpages

|----------------------Service Root URI------------|-----Resource Path-----|--Query Option------|

OData Operations

As mentioned, the OData supports CRUD-style operations. These operations are Read (Retrieve), Create (Insert), Delete, and Update. The OData allows access to resources in the form of services via HTTP requests. Each operation is mapped to a corresponding HTTP method as depicted in Table 2.

It is up to the service provider to support all or some of the operations mentioned. For illustrating the use of operations, I selected a read-write service freely available at the odata.org web site:

https://services.odata.org/V2/(S(xuh52ptttgitgrkbtjzk1o31))/OData/OData.svc/.

This service supports all the above-mentioned operations. While developing mobile applications, the developer needs to write the appropriate coding for carrying out the operations provided by the OData service. However, I use the RESTClient Add-on of the Firefox browser to illustrate the execution of the operations.

Read Operation

Read  operations allow you to read an entire entity set (ReadEntitySet ) or a specific entity within an entity set (ReadEntity), returning a collection of entities (in a feed) or a single entity (in an entry document), respectively. (The HTTP GET request is used for the read operations.)

The ReadEntitySet enables you to get the entities within a particular entity set. You can simply carry out the read operation using the HTTP GET method of the RESTClient Add-on within a browser. For retrieving an entire entity set, use the name of the entity set at the end of the specified URI. For example, for retrieving the entire entity set Categories, this is the URI: https://services.odata.org/V2/%28S%28xuh52ptttgitgrkbtjzk1o31%29%29/OData/OData.svc/Categories.

Figure 7

Response body GET method

In this case, as you can see, the entity set is returned in a feed document that consists of three entries. You can expand a given entry to see its properties.

The ReadEntity operation, on the other hand, lets you retrieve the details of a single entity within an entity set. For testing such an operation using the RESTClient, you use the same GET method and place the URI in the respective field as shown in Figure 8.

Figure 8

GET Request for the ReadEntity operation

Since you need the details of the Category with the ID equal to 1, you use the URI of the ReadEntitySet operation for products, followed by the relevant key (in this case ….Categories([ID=1]).

The response body, in this case, is the one shown in Figure 9.

Figure 9

Response of RetrieveEntity operation

This contains the details of a single entity (i.e., Category 1 [Beverages]). For both operations, after success, the Status Code is the one shown in Figure 10.

Figure 10

Status code 200 OK

For both the read operations, you may have a number of query options after the URI. (This is covered in the next section).

Create Operation

The create operation allows you to create a new entity of a given entity type. The HTTP POST method request is used for carrying out the create operation. The URI supplied must be the same as the one used for retrieving the entity set of the type in question. For example, if you are creating the new Category, use the following URI: ……/Categories.

As a test purpose, use the RESTClient Add-on for the browser that allows you to execute the POST HTTP request. The RESTClient appears as shown in Figure 11.

Figure 11

RESTClient POST method

Make sure that POST is specified in the Method field. Enter the URI in the relevant field. Enter the content of the entry to be created (inserted) in the Body field. Before executing the POST method, you need to specify the Content-Type as application/atom+xml in the Header. The content entered in the Body field is shown in Figure 12.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>

<entry

xmlns:d="https://schemas.microsoft.com/ado/2007/08/dataservices"

xmlns:m="https://schemas.microsoft.com/ado/2007/08/dataservices/metadata"

xmlns="https://www.w3.org/2005/Atom">

 

  <content type="application/xml">

 <m:properties>

   <d:ID m:type="Edm.Int32">3</d:ID>

   <d:Name>Books</d:Name>

 </m:properties>

  </content>

</entry>

Once the URL is correctly entered as well as the body, click the SEND button. If the entity is successfully created, a new Category named Books is created. The Response header shows the Status Code 201 Created and the location of the newly created Category is also shown (Figure 13).

Figure 13

Response header for successful insertion

UpdateEntity Operation

The UpdateEntity operation updates an entity (i.e., changes the existing properties of the entity). The PUT HTTP method is involved in this case. Suppose you have already created a new Category entity (with property CategoryID equal to 3) having the name Books using the Insert operation. You can later change the name of the entity from Books to Books and Ebooks using the update operation.

When using the RESTClient, you enter the following URL in the relevant field:

https://services.odata.org/V2/(S(xuh52ptttgitgrkbtjzk1o31))/OData/OData.svc/Categories(3)

The exact entity that has to be modified must be specified (in this case, Category with ID equal to 3). The content body must be as shown in Figure 14, representing the entity to be updated (partial view).

…..

  <content type="application/xml">

 <m:properties>

   <d:ID m:type="Edm.Int32">3</d:ID>

   <d:Name>Books and Ebooks</d:Name>

 </m:properties>

  </content>

</entry>

Delete Operation

For deleting a particular entity from an entity set, use the delete operation via the DELETE HTTP method. The specified URI must indicate the specific entry that is to be deleted. For the Categories example, suppose you want to delete the entity having the key property CategoryID 2 via the RESTClient add-on. Figure 15 shows the URI that has to be used. The Method DELETE must also be specified.

Figure 15

DELETE Method executed in RESTClient

OData System Query Options

Now you see the OData system query options in detail. Query options are query-string parameters that can be specified to limit the amount and vary the order of the data that an OData service returns. Within the URI, these query options are prefixed with the $ character. An OData service may or may not support the entire query options listed. The service provider decides which of the mentioned Query options are supported.

• $format. This query option lets you retrieve the result set in a specified format. For example, if you want the results in a JSON format, use the query option in Figure 16.

…../Categories(1)/Products?$inlinecount=allpages&$format=json

In this case, the results are shown in JSON format (Figure 17).

Figure 17

Response body in JSON format

In this case, the XML format is to be specified, so the query option looks like the one in Figure 18.

…../Categories(1)/Products?$inlinecount=allpages&$format=xml

• $filter. The $filter query option allows you to filter the results according to certain sets of criteria. In other words, it identifies a subset of the entries in the collection to which it is applied. This may be seen as analogous to the WHERE clause within an open SQL SELECT statement. With this query option, you can use a number of logical and arithmetic operators. Following are a few examples of how you can use this filter query option.

Suppose you want to get the details of the product whose name is Côte de Blaye. Using the filter option, the corresponding query string end looks like Figure 19.

……/Products?$filter=ProductName eq 'Côte de Blaye'

Figure 20

Details of product Cote de Blaye

In case you have a ProductName that has apostrophe in it, you can specify it in the query option by adding an adding an extra apostrophe (’) before the one contained in the name. For example, to read the details of the product where the product name is equal to Sir Rodney’s Marmalade, use the query option in Figure 21.

……..Products?$filter=ProductName eq 'Sir Rodney''s Marmalade'

…..Products?$filter=UnitPrice gt 50

…..Products?$filter=UnitPrice ge 10 and UnitPrice le 65

……..Products?$filter=startswith(ProductName, 'S')

……..Products?$filter=UnitPrice gt 50 and Discontinued eq ‘false’

The query in Figure 25 returns all products with a unit price greater than 50 that are not in a discontinued state.

• $orderby. This query option enables sorting of the retrieved entries with respect to a given property. For example, in the case of the products example, you can sort products according to the unit price or the product name. You have the option of sorting in both ascending or descending order. By default the sorting is ascending. See the example in Figure 26.

...../Products?$orderby=Price

The string in Figure 26 sorts the retrieved products according to the unit price. However, if you want to sort the products using the price but in descending order, add desc as shown in Figure 27.

...../Products?$orderby=Price desc

• $select. Using the $select query option, you can limit the properties contained in the response body. This is similar to the specification of a fields list with the SELECT statement used in Open SQL. If a single property (for example, ProductName) is desired, the query option looks like the one in Figure 28.

……/Products?$select=ProductName

……/Products?$select=ProductName,Price

Figure 30 shows another example of multiple properties along with the filter and order by option.

……$filter=Rating gt 4&$orderby=Price&$select=Rating,Price

In this case, all products that have a rating greater than 4 are returned. These entries are sorted in ascending order based on the price. In addition, only the rating and price properties are included, rather than all product properties.

• $top. The $top returns the first (or top) N number of entries from a specified collection. For example if you want only the top 10 products from the relevant entity set, the following is the query string (Figure 31).

...../Products?$top=10

• $skip. As the name denotes, this query option skips a particular number of entities from a given collection. For example if you want to skip the first 10 entries, use the following string in Figure 32.

...../Products?$skip=10

...../Products?$top=10&$skip=20

• $count. This query option allows you to retrieve the total number of entries identified by a resource path (and any other query string parameter used). In this case, only a single raw value pertaining to the number of the entries is shown (Figure 34).

…./Products/$count

Figure 35 shows another example.

…..Categories(1)/Products/$count

In Figure 36 the resource path and filter query option identifies all products that have products with names beginning with the letter B. The total number of these products is returned as a raw value.

…./Products/$count/?$filter=startswith(Name, 'B')

• $inlinecount. In contrast to the $count query option, the $inlinecount option allows you to include the identified entries by the resource path and the query options in the response body along with total count of the entries (Figure 37).

…… /Products/?$inlinecount=allpages

Figure 38

Response body with count value

Figure 39 shows another example.

…./Products/?$top=6&$inlinecount=allpages

• $value. This query option is used for retrieving the raw value of a particular property of a given entity. Figure 40 shows another example.

…..Products(1)/Rating/$value

In this case, the rating of the Product having the ID 1 is returned. In case the $value is not used, the Rating of the Product 1 is displayed in XML format. The various query options used in the read operations URI can be seen as analogous to the different elements of a SELECT statement written in Open SQL. Figure 41 shows the similarities.

GET URI format used in OData Retrieve Operation:

  Root URI~/EntitySet?$filter=...&$orderby=...&$top=...&$select

Similar to Open SQL Statement having the form:

  SELECT ($select) FROM EntitySet

    WHERE ($filter)

    ORDER BY ($orderby)

    UP TO ($top) ROWS