SAP HANA SPS 09: New Developer Features; REST API

This blog is part of the larger series on all new developer features in SAP HANA SPS 09:http://scn.sap.com/community/developer-center/hana/blog/2014/12/02/sap-hana-sps-09-new-developer-features

The SAP HANA Repository is a key feature of the HANA native development environment.  It is the design time archive for all development objects from database tables all the way up through user interface artifacts. However up until now we’ve not had a supported API which would allow application developers or 3rd party tools developers to access the Repository.  With the advent of the Web-based development tooling, SAP needed to create a REST-based service interface for these development tools.  These two requirements come together in SPS 09 in the form of the newly released SAP HANA REST API.

Eclipse Orion

For the Web-based development tools, SAP decided to use the Eclipse Orion API. The REST API 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 or the Web-based Development Workbench 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.

API Parts

The REST API has several parts which we will look at briefly in this blog. This is just intended to be an introduction to the basic capabilities.  For more details, please refer to the online help: http://help.sap.com/hana/SAP_HANA_XS_REST_API_Reference_en/index.html

• File API
• Workspace API
• Transfer API
• Metadata API
• Change Tracking API
• OData Service
• Info API

File API

The SAP HANA REST Application Programming Interface (REST API) includes a file API that enables you to browse and manipulate files and directories via HTTP. The File API included in the SAP HANA REST API uses the basic HTTP methods GET, PUT, and POST to send requests, and JSON is used as the default representation format. For more information about the original Orion File API, on which the File API is based, see http://wiki.eclipse.org/Orion/Server_API/File_API.

Retrieve the contents of a file (http://wiki.eclipse.org/Orion/Server_API/File_API#Getting_file_contents).

You can also retrieve the contents of a particular version of the file (URL-parameter version) or check the ETag of the current version of the file (using the “If-Match” parameter).

The file API supports a conditional “If-None-Match”, too. Note that providing a header for the “If-None-Match” results in the return code 304 (Not Modified) if the file was already requested in the current session and the file was not changed since the last request.

If you specify a value for the parameter Workspace in SapBackPack, the file API returns the most recent inactive version of the file in the given workspace, if it exists. If no inactive version of the requested file exists in the specified workspace, then an active version of the file is retrieved. The default workspace is “” (empty string).

Here is a small example taken from an SAPUI5 application where we use this API via jQuery.AJAX to load the content of a file from the Repository:

var ShortUrl = '/sap/hana/xs/dt/base/file/';
var package = oExerciseJSON.exercises[i].steps[isub].package;
var lPath = package.replace(/[.]/g, '/');
var aUrl = ShortUrl + lPath;
aUrl = aUrl + '/'
                + oExerciseJSON.exercises[i].steps[isub].object
                + '.'
                + oExerciseJSON.exercises[i].steps[isub].extension;      
                                               
var oSapBackPack = new Object();

oSapBackPack.Workspace='SHINE_DATA';
var sapBackPack = JSON.stringify(oSapBackPack);
               

jQuery.ajax({
                                url : aUrl,
                                method : 'GET',
                                dataType : 'text',
                                headers : {
                                    "SapBackPack" : sapBackPack },
                                success : onInsertContent,
                                error : onErrorCall,
                                async : true
                });

Workspace API

The SAP HANA REST Application Programming Interface (REST API) includes a Workspace API that enables you to create and manipulate workspaces and projects via HTTP. For more information about the original Orion API, on which the Workspace API is based, see http://wiki.eclipse.org/Orion/Server_API/Workspace_API.

The information in this section describes how to use the Workspace API in the context of SAP HANA. To better understand how it can be used, it is essential to understand the meaning of the terms workspace and project in the context of the Eclipse ORION concept.

ORION Workspace

A concept taken over from the Eclipse architecture. A workspace is an area where the design artifacts used in coding or modeling work are located. In this sense, the workspace is user specific; it is the place where a user collects all the smaller entities required for development activities, for example, projects. This Eclipse-based workspace concept is different to the meaning of the workspace currently used in the context of the SAP HANA XS Repository.

ORION Project

A collection of design time and modeling entities that not only have a common storage location, but to which you can also apply activities that typically occur during the development lifecycle, for example: compile, build, distribution, deployment, sharing objects with other developers.

Both ORION concepts are technically mapped to the SAP HANA XS package concept, which means that both are implemented as SAP HANA XS packages with specific content and in a specific location.

So to summarize, when you create a project; it is an SAP HANA XS sub package in the specified workspace package.

Transfer API

The Orion Transfer API is used to import and export packages and files. For more information about the Orion Transfer API, see http://wiki.eclipse.org/Orion/Server_API/Transfer_API.

• This API is used to import and export packages and files
• It supports resumable, chunked uploads of file content
• Export not yet implemented.  Use the File API for export instead.

Currently, there are some restrictions. For example, although the Orion Transfer API supports the upload of single (binary) files also in the form of multiple chunks, it is not possible to use the Orion API to import (or export) a package. Neither is it possible to import files from (or export files to) an external server.

Metadata API

The REST API’s Metadata API provides services to support search and auto-completion scenarios. For example, to retrieve metadata from runtime, design-time and other metadata locations. The typical location of runtime metadata is the SAP HANA database catalog. Currently it is possible to retrieve metadata for tables, views, procedures, functions, sequences, and schemas. The design-time location for metadata is the SAP HANA Repository. Also accessible is the metadata location used by Core Data Services (CDS). All provided services are available at the following (single) access point:

/sap/hana/xs/dt/base/metadata

The specific services are called by setting the HTTP parameter Service-Name to the appropriate value. This part of the interface only supports HTTP GET requests.

Supported Services:

checkMetadataExistence

checkMetadataExistence URI

getMetadataSuggestion

Change Tracking API

The SAP HANA REST Application Programming Interface (REST API) includes a Change Tracking API that enables you to make use of specific lifecycle-management features included with the SAP HANA Repository via HTTP.

Change Tracking is integrated with the SAP HANA XS Repository transport tool set. For example, with change tracking enabled, you can ensure that an export operation includes only the latest approved versions of repository objects.

Note that the API can only be used if change tracking is enabled in the SAP HANA system via the HANA Application Lifecycle Management tool.

OData Services

The SAP HANA REST Application Programming Interface (REST API) includes a set of OData services that enable access to configuration data stored in the SAP HANA environment. The OData services can be accessed with any Odata consumer implementation that supports Odata version 1.0.

The SAP HANA REST API includes the following Odata services.

• Delivery units
• Contents of .ini files
• M_FEATURES

To use the Odata services included with the SAP HANA REST API, the user needs to have the access rights to the underlying SAP HANA runtime views.

Delivery Units

Provides access to “_SYS_REPO”.”DELIVERY_UNITS”

INI File Contents

Provides access to “SYS”.”M_INIFILE_CONTENTS”

M_FEATURES

Provides access to “SYS”.”M_FEATURES”

Info API

The SAP HANA REST Application Programming Interface (REST API) includes an Info API that can be used to display information about the current version of the REST API. The information displayed by the Info API includes a description of the current version of the delivery unit and the number of commands (API entry points) that are currently supported by the REST API.