Performing OData Operations

Each OData service is represented by a URI, called the service root URI. A URI is a uniform resource identifier, which is a string of characters used to identify a resource by name and address. This type of identification enables interaction with representations of the resource across a network using specific protocols like OData.

To consume an OData service for read, you just need a browser and the OData service root URI. The service document is the highest-level description of an SAP Gateway service. It shows the basic information about the available data. From here, it is possible to call further information on the service, and of course the data itself, by adding URI parameters.

To get data from the service, add the name of an entity set of the service to the base URI. You get a list of entities of that type, which could be the content of a database table.

We want to read the BusinessPartnerSet entity set from our OData sample service. The Atom XML response is a feed with multiple entries, which are shown here in a collapsed form so that we only see the third entry. Each entry has a content filled with properties. The properties are the actual data set.

Each entry is identified in Atom by an ID, which is in fact the URI to read the entry. In addition, one or more navigation links can lead to dependent entities.

We now follow the first URI in the metadata section to read just the third entry in the business partner entity set. This URI is also called the self-link of this entity. If you compare this response with the previous one, you’ll see that the entity is identical but without the surrounding feed element.

There are three navigation properties pointing to the SalesOrderSet, ContactSet, and ProductSet. All navigation properties are URIs. As a consumer of an OData service, you can just follow this URI and navigate through this web of data. Let’s do so and fire a GET call at the SalesOrders URI.

The result is a feed of sales orders associated with the selected business partner. While we can see the payload of the third entry, the other entries have been collapsed for readability. Beside the properties of the sales order, there are again navigation links available. These lead further on to the LineItems but also back to the business partner we came from.

One use case for navigation properties is the navigation from one screen that shows the details of a business partner to a second screen that lists all sales orders that are associated with that business partner.

To compare this with the metadata document: in a similar way to properties, navigation properties are specified as part of an entity type. A navigation property is tied to an association. 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. Finally, the association set maps the entity sets to the association.

One of the main features of OData is that it uses the existing HTTP verbs GET, PUT, POST, and DELETE at addressable resources identified in the URI. Conceptually, OData is a way of performing database-style create, read, update, and delete operations on resources through HTTP verbs.

By building URIs based on the rules of OData, a wide variety of data requests can be performed. These requests can often be mapped directly to SQL requests accessing data in a database.

Calling the service URI of an OData service in a GET request, results in the service document. Adding the name of an entity set to the base URI, results in a list or set of all entities. This is called a query request.

Adding the unique key of an entity in brackets to a query request, results in a single entity having this key. Character-based keys must be put in apostrophes. This is called a read request.

Adding a navigation property of the entity type to a read request separated by a slash, results in a single entity or a set of entities depending on the multiplicity of the association. This is called a navigation request.