Skip to Content
Author's profile photo Carlos Roggan

Integration Gateway: Understanding REST data source [12]: Navigation

This  blog is about Integration Gateway in SAP Mobile Platform 3.0 (SMP).

The OData specification describes the concept of navigation, in order to easily navigate from one resource to another one.

REST services can also support a kind of “navigation”, where the result set of one resource depends on another resource.

If we use such a REST service as data source in our Integration Gateway project, we can add the navigation capability to our OData service.

In this tutorial, I’d like to show an example for an easy-to-implement bidirectional navigation.

This tutorial is based on SMP SP07.


The sample REST service is now made available for public usage, so I’ve updated the tutorial to use it.

Also, the code is attached to this blog.


I expect that you’ve gone through my previous tutorials , explaining REST data source, QUERY  and READ  operation.

Please check the Links section for more info.

Furthermore, you need:

  • Eclipse with SAP Mobile Platform Tools installed
  • SMP SP07
  • Basic knowledge about OData provisioning using the Integration Gateway component of SMP


REST Service

For this tutorial, we need a REST service with at least 2 resources that supports that kind of “navigation”.

I’m using a service that is public available, you only need to sign up, afterwards you can access it with your SCN  user and password.

Please see the following document for details:

Getting started with the SAP Netweaver Gateway Service Consumption System

Finally, you should be able to access it via the following URL:

Let’s have a look at how the backend-REST-service is used.

First, we invoke the URL for the “companies”:

The result is a list of “companies”:

We can now choose one single “company”:

The “company” is uniquely identified by the ID field, which is in the URL.

Now, this REST-service allows to add a segment to the URL, in order to retrieve the “contacts” that are responsible for this “company”:

The result is a list of “contacts”, since there can be more than one “contact” for a “company”.

This is a one-to-many relationship.

In the details of a “contact”, we can see the ID of the “company” for which he is responsible.

After navigating from a “company” to its “contacts”, let’s now check the other way ‘round:

Open one single “contact”

Go to the “company” for which this “contact” is responsible:

Here we have a many-to-one relation, so the result is a single entry.

This company is the same that we’ve seen above.

Eclipse Project

We need a SAP Mobile Platform OData Implementation Project that already has the QUERY and READ operations implemented for both resources of the backend-REST-service.

And it should be up and running on our SMP server.

OData Model

The 2 EntityTypes are modeled according to the 2 resources of the backend REST service.

Additionally, we have an association between them.

Note that is has to be a bidirectional association, because we want to navigate from the “Company” to the “Contacts” and as well from a “Contact” to its “Company”.

As we’ve seen above, a company can have many contacts, but a contact can only belong to one company.

So we specify a one-to-many relation.

And we create a Referential Constraint, which maps the property ID (of the Company) to the property COMPANY_ID (of the Contact)

That’s it for the modelling.

Next, we create the bindings and the Custom Code for QUERY and READ operations for both EntitySets.

Since this is explained in my previous blogs, we can skip all explanations about it.

Here are the relative URLs to be used in the Eclipse wizard:

QUERY companies /sap/opu/rest/address/companies
READ company /sap/opu/rest/address/companies/{ID}
QUERY contacts /sap/opu/rest/address/contacts
READ contact /sap/opu/rest/address/contacts/{ID}

Custom Code

After testing the QUERY and READ operations of our OData service at runtime, we can start taking care about the navigation.


We invoke the URL for a company, e.g. https://localhost:8083/gateway/odata/<ns>/<service>/Companies(‘2’)

In the response we can see that the Integration Gateway framework has generated a link element:

What happens, if we invoke that link?


Let’s try it.

Implementing the navigation for one-to-many relation

First we have to understand, that our script for the contact-QUERY is invoked.

The last segment of the URL is the ‘ContactSet’, which means that a collection of contacts is requested.

Therefore, when navigating from company to contacts, the contact-QUERY script is invoked (the default name Contacts_REST_Query.groovy)

Note that this is the case because we have a 1-to-many association between Company and Contact

First, the processRequestData() method is invoked.

And here we have to do the actual work.

The Integration Gateway framework doesn’t know how the backend REST service is designed.

Integration Gateway only knows that the user requested “give me the contacts which are relevant for the-company-with-ID-2”

But it doesn’t know how to get exactly this amount of data.

Therefore, we have to tell, how this is done, because we do know it: the URI has to look as follows:


And we tell it in the processRequestData() method.


Our task is to modify the backend-REST-service-URI that is called by Integration Gateway.

Implementing the processRequestData() method

We’re already familiar with such tasks.

We hock into the HTTP request, before it is fired agains the backend-REST-service.

In the processRequestData() method, we have to obtain the URI and modify it.


Our contact-QUERY script is invoked in both cases, with navigation and without navigation.




Both URLs lead to our script being invoked.

So we have to consider it in our implementation.

Steps that have to be performed:

1) Obtain the UriInfo object

We need it in order to get the information about the navigation, which is in the URL.

     a) We need to know from where the navigation comes.

         In our example, we have only 2 EntityTypes, so the navigation starts always from a “Company”, but for other services it would be different.

         This is realized with the method UriInfo.getStartEntitySet()

     b) We need to know the ID of the “Company”, because depending on it, the amount of “Contacts” is different

        This information is contained in the UriInfo.getKeyPredicates()

2) Obtain the relative URI

We need it, in order to modify it.

This is how the URL that is invoked by the user of our OData service:


and this is how it has to look like when the backend-REST-service is called:


3) Set the relative URI

After correcting the relative URI, it has to be given back to Integration Gateway.

This is done by setting the header in the message object

And here’s the code snippet for our example.

def Message processRequestData(message) {

    UriInfo uriInfo = (UriInfo)message.getHeaders().get(“UriInfo”);

       // check if navigation is in place

    List<NavigationSegment> navSegments = uriInfo.getNavigationSegments();

       if(navSegments.size() < 1){

             // no navigation, just normal getEntitySet operation

             // this is the case for the call to


             return message; // do nothing

    }else if (navSegments.size() > 1){

               /* this would be the case for e.g.

         * <…>/<srv>/Companies(‘2′)/ContactSet(’46’)/Company/ContactSet

         * here the number of navSegments would be: 3

         * */

        log.logErrors(LogMessage.TechnicalError, “Not supported”);

              return message; // ignore it for today


       /* in our example, for the URL 

    * <…>localhost:8083/gateway/<…>/Companies(‘2’)/ContactSet

    * the number of navSegments is: 1

    * */

       // handle the navigation

    String startEntitySetName = uriInfo.getStartEntitySet().getName();

       // we know that our EntityType has only one key field

    KeyPredicate keyPredicate = uriInfo.getKeyPredicates().get(0);

    String keyLiteral = keyPredicate.getLiteral();

       /* in our example, for the URL 

    * <…>localhost:8083/gateway/<…>/Companies(‘2’)/ContactSet

    * the value of keyLiteral will be: 2

    * */

       // this is not really required for our service thathas only 2 EntityTypes:



       String relativeUri = (String)message.getHeaders().get(“RelativeUri”);

             /* in our example, the value is: 

        * /rest/addressbook/contacts


             // here we’re doing the actual work: modify the URI

       String targetRESTuri = relativeUri.replace(

                                 “contacts”, “companies/” + keyLiteral + “/contacts”);


             // finally, set the manipulated REST-service-URI for the navigation

       ((Message)message).setHeader(“RelativeUri”, targetRESTuri);

            /* in our example, the final URI has to look like this:

       *  /rest/addressbook/companies/2/contacts



       return message;


Implementing the processResponseData() method

In terms of navigation, nothing has to be done here.

This method is already implemented for the QUERY operation, we don’t need to change or add anything.


After deploy and configure the service, the navigation can be tried via a URL like this:


The result should be the same like in the backend:


Implementing the navigation for many-to-one relation

The first navigation example was for the 1-to-many relationship.

My sample backend-REST-service also supports to ask a single “contact” for the “company” that he is responsible for.

This is a many-to-1 relationship.

In our OData model, we’ve described this with a bidirectional association.

The OData modeler tool has generated a NavigationProperty called “Company” in the EntityType “Contact”.

Which means that we can invoke a URL like this:


Which corresponds to a backend-REST-service-URL like this:


The implementation is very similar, the difference is:

Since here we have a many-to-1 relation, the script that is called is the Company-READ.

Again the response doesn’t need to be changed, it is just the READ implementation that is used to represent the target entry.

As for the request, the implementation is very similar like above

def Message processRequestData(message) {

  UriInfo uriInfo = (UriInfo)message.getHeaders().get(“UriInfo”);

   List<NavigationSegment> navSegments = uriInfo.getNavigationSegments();

   if(navSegments.size() == 1){

    String startEntitySetName = uriInfo.getStartEntitySet().getName();

    String keyLiteral  = uriInfo.getKeyPredicates().get(0).getLiteral()



         // in our example: /rest/addressbook/companies/46

      String relativeUri = (String)message.getHeaders().get(“RelativeUri”);


         // modify the URI

         // in our example, we need: /rest/addressbook/contacts/46/company

     String targetRESTuri = relativeUri.replace(“companies”, “contacts”) + “/company”;

         // finally, set the manipulated REST-service-URI for the navigation

      ((Message)message).setHeader(“RelativeUri”, targetRESTuri);



  return message;



In this tutorial, we’ve learned how to realize navigation between 2 entities, based on REST data source.

It has been easy to realize, because the used backend-REST-service supported a kind of navigation that was easy to adapt to the OData way.

For other REST services it might be more tricky.


Installing SMP Toolkit:

Tutorial for OData provisioning in SMP:

Preparing Eclipse for Groovy scripting:

Introduction in REST datasource part 1: Understanding the return structure in xml

Introduction in REST data source part 2: Understanding the return structure in json–json-very-simplified

Introduction in REST data source part 3: Implementing the QUERY operation–xml-standard

Introduction in REST data source part 7: Implementing the READ operation–xml

Overview of all REST blogs

The official documentation:

Assigned Tags

      Be the first to leave a comment
      You must be Logged on to comment or reply to a post.