Skip to Content
Author's profile photo Thomas Jung

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.

HANABlog62.png

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.

Assigned Tags

      6 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Jordan Jordanov
      Jordan Jordanov

      Is it possible to import a DU using this web API?

      Or it is possible only via regi tool (asking in the context of automating the deliver of a XS app from one HANA to another via command script)

      And thanks for the blog.

      Author's profile photo Thomas Jung
      Thomas Jung
      Blog Post Author

      No. Such life cycle management features aren't in the scope of this API. HALM does already have its own command line tool, hdbalm, since SPS 08:

      https://hcp.sap.com/content/dam/website/saphana/en_us/Technology%20Documents/HANA_SPS08_NEW_HALM.pdf

      Author's profile photo Naresh Kumar Margam
      Naresh Kumar Margam

      Hi Thomas,

      Thanks for the informative blog. I understand that there are different APIs to extract information from HANA. However, still confused of what would suit my requirement.

      I'd like to extract information related to - HANA Users, Roles assigned to the Users.
      Firstly, Is it even possible to extract this Security information from HANA DB ? which APIs could support this feature ? I have read a document on SAP Identity Management - Connector Overview which talks on the same areas.

      Could you please provide any leads on this topic ?

      Regards,

      Naresh

      Author's profile photo Yang Song
      Yang Song

      @Thomas Jung do you know how to use xsjs to send file to the ftp server or download file from the ftp server, thanks.

       

      Author's profile photo Former Member
      Former Member

      Hello Thomas,

      Thanks for this post, this is a very interesting feature.

      I have a need to change/activate some HANA artifacts through an automatic process such as an job and it seems to me that this REST API could be the perfect tool to cover it.

      More precisely, I have for example an issue with runtime-time versions of hdbrole which are loosing virtual tables when we delete/re-create them (only way for now to update virtual table structure when virtualized table structure has changed), and therefore the runtime-object has to be redeployed from design-time version manually. This is one of the use-cases where an automatic job re-deploying role each nights could be really useful (because persons responsible for virtual table update and persons responsible for role maintainance are different) !

      However, I'm struggling with the fact that I want to make those actions on the same HANA server than the one which will be executing the xsjs script and therefore I need to perform http GET/POST/PUT from server side on itself (the client will be the server sending request to itself).

      I have seen some pieces of code involving xshttpdest, however if I understood well ,the http destination needs to be in the same package than manipulated artifacts, which doesn't suits my need (I want it to be generic and "package-wide").

      Do you know if there is any way to perform, let's say "relative", http GET/POST/PUT from xsjs when wanting those requests hitting the "localhost"? Or do you have any suggestions regarding a best way to do it? (or am I completely loony ^^ ?)

      Thanks in advance for your feedback and thank you for all your (very useful) contributions over the SAP communities !

      Xavier.

      Author's profile photo Thomas Jung
      Thomas Jung
      Blog Post Author

      No there is no relative local request.  You must use XSHTTPDEST for this.