SAP NetWeaver Gateway speaks OData with SAP Annotations

When reading the announcement for SAP NetWeaver Gateway or the SAP NetWeaver Gateway page in SDN, the sentence I like most is that Gateway is “leveraging REST services and OData/ATOM protocols”. Let me explain why.

Why REST?

I don’t want to get into the discussion of “SOAP versus REST”, that’s far too dangerous a battleground for me to enter lightheartedly, so I’ll just list the three main reasons why I personally like REST:

• I can use my browser to see what data I will get.
• If I’ve got one snippet of information, it will most likely lead me to other, related snippets of information.
• If I know where to GET data, I know where to PUT it, and I can use the very same format.

I’ve used SOAP services for some time, and every single one of the above would have made my life easier.

Why OData?

AtomPub is the de-facto standard for treating bunches of similar information snippets (just look around who else is using it … or who isn’t J). It’s simple, it’s extensible, and it allows putting anything into its content. Well, anything textual at least, and you can use media link entries to point to the binary stuff.

Now a lot of the textual enterprise data we deal with is structured, so we need some way to express what structure to expect in a certain kind of information snippet.

And as these snippets can come in large quantities, we need to trim them down to manageable chunks, sort them according to ad-hoc user preferences, then step through the result set page by page.

OData gives us all of these features, and some more, like feed customization that allows mapping part of the structured content into the standard Atom elements, and the ability to link data entities within an OData service (via “…related…” links) and beyond (via media link entries). So we can support a wide range of clients with different capabilities:

• Purely Atom, just paging through data
• Hypermedia-driven, navigating through the data web, and
• Aware of query options, tailoring the OData services to their needs

And beyond that OData is extensible, just as the underlying AtomPub, so we can add some features that we discovered to need when building easy-to-use applications, both mobile and browser-based.

Why SAP Extensions?

What do we need for building user interfaces? First of all, human-readable, language-dependent labels for all properties.

Next, we need free-text search, within collections of similar entities, and across. OpenSearch to the rescue: it can use the Atom Syndication Format for its search results, so the found OData entities fit right in, and it can be integrated into AtomPub service documents via links with rel=”search”, per collection as well as on the top level. The OpenSearch description specifies the URL template to use for searching, and guess what: for collections it just points to the OData entity set, using a custom query option with the obvious name of search.

For apps running on mobile devices, we want to seamlessly integrate into contacts, calendar, and telephony, so we need semantic annotations to tell the client which of the OData properties contain a phone number, a part of a name or address, or something related to a calendar event.

Not all things are equal, and not all entities and entity sets will support the full spectrum of possible interactions defined by the uniform interface, so capability discovery will help clients avoiding requests that the server cannot fulfill, so the metadata document will tell whether an entity set is searchable, which properties may be used in filter expressions, and which properties of an entity will always be managed by the server.

Most of the applications we are focusing on now for “light-weight consumption” follow an interaction pattern called “view-inspect-act”, “alert-analyze-act”, or “explore & act”, meaning that you somehow navigate (or are lead) to an entity that interests you, and then you have to choose what to do. The chosen action will eventually result in changes to this entity, or entities related to it, but it may be tricky to express it in terms of an update operation, so we advertise the available actions to the client as special atom links – with an optional embedded simplified “form” in case the action needs parameters – and the action is triggered by POSTing to the target URI of the link.

Putting all that together we arrive at the following simplified picture:

And Gateway isn’t the only SAP product speaking OData with SAP extensions: SAP HANA also allows accessing views and tables as OData services.

I’m curious to see what people will build with OData on top of SAP NetWeaver Gateway or directly on SAP HANA!