Tutorial: 1. Orion-based API to HANA

1. Orion-based API to HANA

Contents

Overview

Orion is an open source effort under the Eclipse project. Orion aims to create a Browser-based IDE framework. The tools are written in JavaScript and run inside the Browser. More information can be found on the Orion Website.

The SAP HANA Orion-based REST API is an implementation of the Orion Server API on HANA. It is an API layer completely supporting the Orion protocol version 1.0 which enables Development Tools to access HANA platform components such as the repository via REST based calls in an easy and flexible manner. As an example the API provides means for the creation and manipulation of workspaces, projects and files but also covers HANA-specifics such as activation and catalog access. Any development tool using the REST API can be used as a client. This opens up HANA as a development environment not just for SAP development tools such as Web IDE but also for tools coming from Partners and Customers.

As a consequence, existing tools implemented on top of the Orion Server API are able to work with HANA. This enables SAP-external communities who would like to use their own tools in a "bring-your-own-tool" (BYOT) manner and allows them to integrate HANA nicely into their established development and management workflows and tools infrastructure.

Technical Aspects

The Orion-based REST API is a HANA component and shipped with the standard HANA platform installation. Currently, it runs natively on the XS engine (Server API implementation) and in the connected Browser (via JavaScript client proxies for accessing the server part). It requires no further client side installation or additional configuration. It is built as a combination of server side JavaScript libraries and files (.xsjslib, .xsjs) which expose the technical REST API via HTTP and client side JavaScript components which can be used to perform valid REST calls against the server.

Relation to the Eclipse Orion Documentation

IMPORTANT: This documentation is meant to be read in addition to the Eclipse Orion documentation, which can be found here.

Therefore, this documentation is mainly concentrating on implementation details of and the enhancements of the REST protocol provided by the HANA XS based components. The study of the Eclipse Orion documentation is highly recommended to get a complete understanding.

This documentation relates to the following parts of the HANA REST API, which are implemented fully compliant to the Orion standard:

  • File API
  • Workspace API
  • Transfer API

SAP-specific Extensions (sapbackpack)

SAP specific functionality such as activation are added in the REST request as additional parameters to the Orion API call. This section describes how to use an additional parameter (SapBackPack) in order to extend the original Orion-functionality in the context of HANA.

The parameters can be added either directly in the URL or may be composed in a special SapBackPack parameter. The detailed description of the parameter usage can be found in the technical documentation of Orion Server API.

The obtained Orion compliant JavaScript components can be used to access SAP HANA capabilities,not specified in the Orion standard (by keeping 100% compliant to this standard). The approach, called "Liquid Signatures", uses JavaScript capabilities as script language: weak typing and weak interface checks at compile and runtime. Each function specified in Orion is implemented with full signature fTest( a,b,c ) { }. Each extended function implements also one additional (complex) parameter carrying sap specific attributes and values for this function in order to use SAP HANA additional functionality: for example, sapBackPack.aTest = 42.

  • Standard consumption causing standard behaviour is var result = fTest( a,b,c ) ;
  • Enhanced consumption causing usage of SAP HANA specifics is var result = fTest( a,b,c, sapBackPack ) ;

The Orion client can be used this way for handling HANA capabilities by staying compliant to the standard and by being open for externally developed components.

If the fileclient component is used a typical code sequence for using SapBackPack looks as follows:

Code Example

var sapBackPack = new SapBackPack();

sapBackPack.Activate = true;

Direct access of API methods via HTTP REST requests can also use SapBackPack by adding a variable of this type to the request header:

Code Example

var oSapBackPack = {};

oSapBackPack.test = "abc";

var sapBackPack = JSON.stringify(oSapBackPack);



$.ajax({

  ...

  headers: {

  "Orion-Version": "1",

  "Content-Type": "application/json",

  "SapBackPack" : sapBackPack,

  ...

  },

  ...

});

X-CSRF-Token

In order to prevent XSRF based attacks on the REST API an X-CSRF-Token must be generated by each PUT/POST/DELETE request. Otherwise, "An attacker can use this to silently trick a developer or administrator in creating a new XSEngine application which provides a persistent backdoor or steals session tokens from other users." (security report). Below is an example of how to generate and use X-CSRF-Token by sending HTTP requests to the REST API.

$.ajax({

 url: "/sap/hana/xs/dt/base/server/csrf.xsjs",

 type: 'HEAD',

 headers: { "X-CSRF-Token": "Fetch" },



 success: function(data, textStatus, jqXHR) {

     if(jqXHR.getResponseHeader("x-sap-login-page")){

           return;

     }

     var securityToken = jqXHR.getResponseHeader("X-CSRF-Token");

     // save securityToken locally

 }

});



// write file

$.ajax({

 url: "/sap/hana/xs/dt/base/file/sap/hana/xs/testProjects/testOrionAPI/work/.test1",

 type: 'PUT',

 data: "test",

 headers: {

     "Orion-Version": "1",

     "Content-Type": "text/plain",

     "X-CSRF-Token": securityToken

 }

});

Error handling

The error handling in HANA REST API is implemented using the Orion error structure.

There are three types of HTTP return codes provided by the HANA REST API:

  1. Standard HTTP/Orion return codes.
  2. Slightly modified HTTP/Orion return codes.
  3. HANA specific error codes.

The first group contains the standard HTTP return codes, which are mostly provided if using HANA REST API according to the native Orion description. The following example returns 404 (Not found) error, if the requested file is not in the package, and HTTP code 200 otherwise.

Example Request


GET /sap/hana/xs/dt/base/file/MyProj/myfile2.txt

Example Response

{

 "HttpCode":404,

 "Severity":"Error",

 "Message":"File not found: MyProj/myfile2.txt"

}

The second group contains the return codes, which are slightly modified compared to the return codes provided by the the Orion specification. In the following example a file is successfully written to the package, but could not be activated after this. In this case the HANA REST API returns HTTP code 202 instead of 200 (as described by the Orion documentation). Additionally a structure CheckResult is provided, which contains the HANA specific information.

Example Request

PUT /sap/hana/xs/dt/base/file/MyProj/myfile.xsjs

Orion-Version: 1.0

X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"

Content-Type: text/plain

This is the new contents

Example Response

HTTP/1.1 202



{

"Name": "myfile.txt",

"Location": "/sap/hana/xs/dt/base/file/MyProj/myfile.xsjs",

"Attributes":

{

 "SapBackPack" : {'Activated' : false}

}

...



"CheckResult" :

{

"Operations":{"Write":true,"Activate":false},

"location":"line 1 position 11 in MyProj/myfile.xsjs",

"error_code":40117,

"error_msg":"SyntaxError: missing ( before formal parameters (line 1 position 11 in MyProj/myfile.xsjs)",

"severity":3

}



}

In the third group the HANA specific errors are handled. HTTP code 555 is used for this purpose. The error is provided if a user requested some HANA specific operation (like activation) directly. The following example returns HTTP code 555, because the activation explicitly requested by providing a SapBackPack parameter to the HTTP request failed. Additionally a structure CheckResult is provided, which contains the HANA specific information.

Example Request

PUT /sap/hana/xs/dt/base/file/MyProj/myfile.xsjs?parts=meta

Orion-Version: 1.0

X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"

Content-Type: application/json



{

"Attributes": {

"SapBackPack" : {'Activated': true}

}

}

Example Response

{

 "HttpCode":555,

 "Severity":"Error",

 "Message":"Error while activating file: MyProj/myfile.xsjs"



 "CheckResult" :

 {

  "Operations":{"Write":true,"Activate":false},

  "location":"line 1 position 11 in MyProj/myfile.xsjs",

  "error_code":40117,

  "error_msg":"SyntaxError: missing ( before formal parameters (line 1 position 11 in MyProj/myfile.xsjs)",

  "severity":3

 }

}

Naming

  • URL: /sap/hana/xs/dt/base/
  • Package: sap.hana.xs.dt.base
  • HDB-Schema: SAP_HANA_RESTAPI
  • Delivery Unit: HANA_DT_BASE