Intro

Welcome to the final post in my first blogging series about calling outbound https services with server side Java Script using the HANA XS engine. In the first post you learned about setting up your HANA box to use SSL/TLS. The second part explained how to configure the trust relations. Now we are going to use the SSL configuration and the prepared trust store in an actual XS application.

This is the list of all three posts:

• Outbound httpS with HANA XS (part 1) – set up your HANA box to use SSL/TLS
• Outbound httpS with HANA XS (part 2) – set up the trust relation
• Outbound httpS with HANA XS (part 3) – call the https outbound service in XS server side JavaScript (xsjs)

Prerequisites

You may have come to this post directly without going through the first two. If so, I don’t want to push you to read the other ones, although I’d be happy if you did 😉 .

So I’ll just summarize, what should have been done so far:

• Your HANA box has got a running https configuration
• The target service certificate has been exported
• That certificate has been imported into an XS trust store (via the XS admin web tool)

In my example I am going to use https://api.github.com as the target service. Of course any other https service endpoint will do as well.

I prefer to use lightweight tools, so I am not going to use the HANA Studio to create and deploy the application.

I’d rather go for the XS Web IDE. It is delivered as non automated content and needs to be manually deployed. This can be done via

• Studio->Quick launch->Import DU->Server …. IDE/Editor

Just let me know if you need any additional support here.

Create and use the https destination

To call the external https service we are going to set up an XS http destination (xshttpdest), link our trust store to that destination and finally call the service in a server side JavaScript (xsjs) file.

Create a new application

If you just want to play or you do not already have an XS application follow these steps:

• Go to your web IDE ( https://<host>:43<InstNo>/sap/hana/xs/ide/ )
• Using the menu, select:

Project->Project Templates->Create Empty Project

• For the ‘Absolute Projectname’ (aka name of the package) you could provide: ‘/github‘

This will result in an empty project, meaning that you have created a package/folder, which contains two files: .xsaccess and .xsapp.

Create the .xshttpdest

The XS http destination file is the configuration description of the service you want to use. So it represents some meta data in which you can set several parameters like destination host, proxy configuration and (of course most importantly) whether to use SSL or not.

For a detailed reference of the parameters please check the HANA Developer Guide at section 3.7.

The destination is created via:

• Right clicking the package which will contain the files;
• Selecting the entry ‘new file’;
• Providing /github/github.xshttpdest as the file name;

(It is important to remember the file’s name, as that name is going to be used it in our xsjs.)

• The content should be similar to the following code snippet:

github.xshttpdest

description = "github api httpS connection";
host = "api.github.com";
port = 443;
useProxy = true;
proxyHost = "proxy";
proxyPort = 8080;
authType = none;
useSSL = true;
timeout = 0;

• Finally, save and activate this file.

Link the destination to the Trust Store

Did I say we are done with the setup in the last post? Well, I guess I was not totally honest with you (sorry!), but I promise this really is the last thing you need to configure! So let’s get it done quickly.

• Open the XS admin tool (remember? It is available at https://<host>:43<InstNo>/sap/hana/xs/admin/ )
• Via the ‘XS applications’ tab
  • Choose your package
  • Select the http destination
  • Within the details area, you need to scroll down to the ‘Authentication’ section and set the following:
    • Authentication type: None;
    • Use SSL: YES;
    • Trust store select the trust store, which contains the target certificate:
      • In my example this is api github;
    • Trigger the ‘Save’ button.

Write server side JavaScript code using this destination

Now you finally have set up everything, and you should be able to call this service from anywhere in your application.

The default way to do it can be found in the reference, available at

• http://help.sap.com/hana/SAP_HANA_XS_JavaScript_Reference_en/$.net.http.Client.html ;
• http://help.sap.com/hana/SAP_HANA_Developer_Guide_en.pdf ;
  • Section 8.4

There is just a small modification: Github’s API wants us to send a ‘User-Agent’. So we are going to send one, of course.

In this example it will look like the following:

issues.xsjs (also attached)

try {
    //readDestination(package, destination_name)
    var destination = $.net.http.readDestination("github", "github");
    var client = new $.net.http.Client();
   
     var request = new $.net.http.Request($.net.http.GET, "/users/SAP");
     // api.github.com wants a user agent, so we have to provide it
     request.headers.set('User-Agent', 'hana-xs-demo-app');
   
     var response = client.request(request, destination).getResponse();
     //The rest of the file (attached) is just a default forward of the response
  var myCookies = [], myHeader = [], myBody;
    //Cookies
    for(var c in response.cookies) {
        myCookies.push(response.cookies[c]);
    }
    //Headers
    for(var h in response.headers) {
         myHeader.push(response.headers[h]);
    }
    //Body
    if(response.body)
        try{
             myBody = JSON.parse(response.body.asString());
        }
        catch(e){
            myBody = response.body.asString();
        }
    $.response.contentType = "application/json";
    $.response.setBody(JSON.stringify({
        "status"    : response.status,
        "cookies"   : myCookies,
        "headers"   : myHeader,
        "body"      : myBody
        }));
}
catch (e) {
    $.response.setBody(e.message);
    $.response.status = $.net.http.INTERNAL_SERVER_ERROR;
}

Please mind the signature of the ‘readDestination’ method. It expects the package/folder, which contains the destination as the first and the actual name of the destination as a second parameter:

     readDestination(package, destination_name)

Once you’ve saved and activated this file, your package should look like:

and you should finally be able to call it. If this is what you see:

Then you’ve made it  – congratulations!

Video

Of course I also can show this interactively:

Outlook, conclusion and where to go from here

As HANA XS is a pretty young product you can look forward to more features coming your way soon. They are currently under development and I will try to keep you updated on their progress.

Anyway, you now have another powerful piece of technology right in your hand and can explore it by using, for example API sites like Programmable Web or API hub (you also may want to look at the API evangelist serving as a good introduction to APIs).

I hope these posts were useful and enjoyable to you.

I would also like to take the opportunity to send a big THANK YOU to Bjoern Friedmann(@BjoernFriedmann) for his support in helping me getting into those nitty-gritties of the technical complexities.

Stay tuned for more

Kai-Christoph