REST API Developer Guide

PUBLICSAP HANA Smart Data Integration and SAP HANA Smart Data Quality 2.0 SP03Document Version: 1.0 – 2020-05-21

REST API Developer Guide

© 2

020

SAP

SE o

r an

SAP affi

liate

com

pany

. All r

ight

s re

serv

ed.

THE BEST RUN

Content

1 SAP HANA Smart Data Integration REST API Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Download and Deploy the SAP HANA Smart Data Integration REST API Delivery Unit. . . . . . . . 6

2.1 Download the SAP HANA Smart Data Integration REST API Delivery Unit. . . . . . . . . . . . . . . . . . . . . .6

2.2 Deploy the SAP HANA Smart Data Integration REST API Delivery Unit from SAP HANA Studio. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.3 Deploy the SAP HANA Smart Data Integration REST API Delivery Unit from SAP HANA Lifecycle Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

3 Overview of SAP HANA Smart Data Integration REST API Methods. . . . . . . . . . . . . . . . . . . . . . 9

3.1 GET/tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

3.2 GET /tasks/<taskName>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

3.3 GET /tasks/<taskName>/tableTypes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

3.4 POST /tasks/<taskName>/executions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

3.5 GET /tasks/<taskName>/executions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

3.6 GET /tasks/<taskName>/executions/messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

3.7 GET /tasks/<taskName>/executions/<execId>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

3.8 GET /tasks/ <taskName>/executions/<execId>/partitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

3.9 GET /tasks/<taskName>/executions/<execId>/operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . .28

3.10 GET /tasks/<taskName>/executions/<execId>/messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

3.11 PUT /tasks/ <taskName>/executions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

3.12 DELETE /tasks/<taskName>/executions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

3.13 PUT /tasks/<taskName>/executions/<execId>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

3.14 DELETE /tasks/<taskName>/executions/<execId>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

3.15 GET /virtualTables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

3.16 GET /virtualTables/<table>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

3.17 GET /virtualTables/<table>/properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

3.18 PUT /virtualTables/<table>/properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42

3.19 POST /virtualTables/<table>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

3.20 DELETE /virtualTables/<table>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

2 P U B L I CREST API Developer Guide

Content

1 SAP HANA Smart Data Integration REST API Overview

Use the SAP HANA smart data integration REST API to programmatically execute and monitor flowgraphs, to process data for interactive data transformation within your application, and to create, modify, and delete virtual tables.

The following diagram gives you an overview of the REST API architecture:

You create, save, and activate flowgraphs in Web IDE. Upon activation, the software automatically creates a task and you use that task at runtime to execute.

The REST API uses the term task to represent the concept or object that is being executed based on a particular flowgraph model.

Here is a high-level overview of what you can do with the REST API:

● Control the execution and monitoring of periodic batch loads and extracts of data within your HANA instance or application based on HANA.

● Expose custom data quality or transformation services to your applications (both HANA and non-HANA) using HANA’s built in data quality/transformation features. For example, you can:○ Perform address cleaning or validation at point of entry in applications.○ Perform geocoding to append a LAT/LONG given to an address for spatial analysis or display on a map.○ Perform reverse geocoding in a mobile application to find nearby addresses to your given location.

REST API Developer GuideSAP HANA Smart Data Integration REST API Overview P U B L I C 3

○ Perform data masking at point of entry in your application to protect sensitive information.

NoteAny single or combination of transformations you can model in a flowgraph can be exposed as a transactional task and thus called using this REST API on HANA. The applications calling the REST API may be running on HANA itself or not running on HANA at all and just using HANA as the engine for performing these tasks.

● Kickoff the execution and monitor realtime data loads to your HANA instance or application on HANA.● Create, modify, and delete virtual tables.

You can execute and monitor the following runtime behavior types using the REST API:

Runtime Behavior Type Description

Batch A batch task is a task that executes once on a batch of records (however many records are in the source).

Batch tasks have the following characteristics:

● One batch loads or extracts at one time.● They are typically larger volumes of data.● They are typically long running.

Transactional Transactional tasks are created when a flowgraph or task has table type input and output(s) and the client wants to call the task for single record processing rather than batch. A transactional task can be created in Web IDE.

Transactional tasks have the following characteristics:

● Typically used to process one record of data or very low volumes at a time.● Typically used to transform the data within an application, but can support multiple re

cords.● Typically used with transient data that is not yet persisted. Such as performing data

quality or transformations on data that is entered into a UI in an application.

You can use the following data types as input to a transactional task:

● Character string types: VARCHAR, NVARCHAR, ALPHANUM, SHORTEXT● Numeric types: TINYINT, SMALLINT, INTEGER, BIGINT, SMALLDECIMAL, DECIMAL,

REAL, DOUBLE● Datetime types: DATE (YYYY-MM-DD, YYYY/MM/DD, YYYY/MM-DD, YYYY-MM/DD,

YYYYMMDD), TIME (HH24:MI:SS, HH:MI[:SS][AM][PM], HH12:MI[:SS][AM][PM], HH24:MI[:SS])

NoteDate and time values that are presented by the REST API reflect the ISO 8601 format, which includes both a date and a time (for example, 2018-01-31T15:30:42.359Z). In the case of transactional task processing, which supports only a DATE or a TIME data type, processed date values will be returned with a time of 00:00:00.000 and processed time values will be returned with a date of 0001-01-01.

● Boolean type: BOOLEAN (TRUE, FALSE, UNKNOWN, NULL)


SAP HANA Smart Data Integration REST API Overview

Runtime Behavior Type Description

Realtime A realtime task encompasses an initial load, plus a realtime replication of the changes since the initial load completed.

The runtime artifact is a stored procedure that calls the initial load task and enables the replication. The changes in the source system then trigger the realtime replication and call to the realtime task.

Realtime tasks have the following characteristics:

● Single flowgraph that encompasses an initial load and real-time replication of changes in a source system.

● Typically a large volume upfront load.● Many continuous replication loads of small volume to synchronize the changes in the

source system to the target HANA system.

For more information about run-time behavior types, see the Modeling Guide for SAP HANA Smart Data Integration and SAP HANA Smart Data Quality.

Related Information

Download and Deploy the SAP HANA Smart Data Integration REST API Delivery Unit [page 6]Overview of SAP HANA Smart Data Integration REST API Methods [page 9]Choosing the Run-time Behavior

REST API Developer GuideSAP HANA Smart Data Integration REST API Overview P U B L I C 5

https://help.sap.com/viewer/71c4a6e6b4dc4a5ab3e17bb1d7e98104/2.0_SPS04/en-US/ed5bc86bb5b049d09704e00f173a6cb7.html

2 Download and Deploy the SAP HANA Smart Data Integration REST API Delivery Unit

Download and import the SAP HANA Smart Data Integration REST API delivery unit using SAP HANA studio or SAP HANA Application Lifecycle Management.

You will need to download the SAP HANA Smart Data Integration REST API delivery unit. Then, using SAP HANA studio or SAP HANA Application Lifecycle Management tools, deploy the delivery unit.

Related Information

Download the SAP HANA Smart Data Integration REST API Delivery Unit [page 6]Deploy the SAP HANA Smart Data Integration REST API Delivery Unit from SAP HANA Studio [page 7]Deploy the SAP HANA Smart Data Integration REST API Delivery Unit from SAP HANA Lifecycle Management [page 8]

2.1 Download the SAP HANA Smart Data Integration REST API Delivery Unit

Download the SAP HANA smart data integration REST API delivery unit from the SAP Support Portal.

Context

The SAP HANA smart data integration REST API delivery unit is available in the same download area as the data provisioning agent.

Procedure

1. Open the SAP Software Download Center .2. In the Installations area, in the search box at the top of the window, enter the search term hana im api

<version number>.

3. Select the name (link) of the version of the zip file to download, save it to a local folder, and open the zip file.


Download and Deploy the SAP HANA Smart Data Integration REST API Delivery Unit

http://help.sap.com/disclaimer?site=http%3A%2F%2Fsupport.sap.com%2Fswdc

4. Extract the .tgz file. This is the delivery unit file to import into SAP HANA.

Related Information

SAP HANA smart data integration and all its patches Product Availability Matrix (PAM) for SAP HANA SDI 1.0

SAP HANA smart data integration and all its patches Product Availability Matrix (PAM) for SAP HANA SDI 2.0

2.2 Deploy the SAP HANA Smart Data Integration REST API Delivery Unit from SAP HANA Studio

You can import the SAP HANA smart data integration REST API delivery unit from SAP HANA Studio.

Prerequisites

Ensure that you have been granted the SYSTEM privilege REPO.IMPORT to be able to import the DU.

Procedure

1. Log in to SAP HANA Studio as user SYSTEM.

2. In the upper left corner, click File Import .3. On the Import dialog, type delivery into the search box for Select an import source.

4. Click Delivery Unit on the resulting navigation tree and click Next.5. Select <your SAP HANA Server name>, and click Next.

6. On the Import Through Delivery Unit dialog, select either the Client or Server radio button, depending on whether the delivery unit is on the client or server machine.a. If you select Client, click Browse and navigate to the location where you downloaded the HANA IM API

delivery unit, select HANAIMAPI.tgz, and click Open.b. If you select Server, then select the DU you want to import from the dropdown list.

7. Click Finish.8. To initialize the SAP HANA smart data integration REST API so that it is ready for use, use a Web browser or

third-party tool to execute a one-time call while using the SYSTEM credentials in conjunction with basic authorization:

GET http://<host>:<port>/sap/hana/im/api/v1/install

REST API Developer GuideDownload and Deploy the SAP HANA Smart Data Integration REST API Delivery Unit P U B L I C 7

http://help.sap.com/disclaimer?site=https%3A%2F%2Fsupport.sap.com%2Fcontent%2Fdam%2Flibrary%2Fssp%2Finfopages%2Fpam-essentials%2FTIP%2FPAM_HANA_SDI_1_0.pdf




2.3 Deploy the SAP HANA Smart Data Integration REST API Delivery Unit from SAP HANA Lifecycle Management

You can import the SAP HANA smart data integration REST API delivery unit through SAP HANA Lifecycle Management.

Procedure

1. If not already granted, grant the role sap.hana.xs.lm.roles::Administrator to the user name you will use to log in to SAP HANA Lifecycle Management.a. In the SAP HANA studio Systems view, expand the name of your SAP HANA server and choose

Security Users System .b. On the Granted Roles tab, click the green plus icon in the upper left corner.c. On the Select Roles dialog, type lm in the search string box.d. Select role sap.hana.xs.lm.roles::Administrator and click OK.

2. Access SAP HANA Application Lifecycle Management by typing the following URL in a web browser:<host name>:80<2-digit instance number>/sap/hana/xs/lm

3. Log in to SAP HANA Application Lifecycle Management as the user name you authorized in step 1.The first time you log in, a pop-up window appears to enter a name for this server.

4. On the SAP HANA Application Lifecycle Management Home tab, click the Delivery Units tile.5. Click the Import tab.6. Click Browse and navigate to the location where you downloaded the delivery unit, select the *.tgz file,

and click Open.7. Click Import.

After successful import, the name of the API appears in the list of delivery units on the left.8. To initialize the SAP HANA smart data integration REST API so that it is ready for use, use a web browser or

third-party tool to execute a one-time call while using the SYSTEM credentials in conjunction with basic authorization:

GET http://<host>:<port>/sap/hana/im/api/v1/install


Download and Deploy the SAP HANA Smart Data Integration REST API Delivery Unit

3 Overview of SAP HANA Smart Data Integration REST API Methods

Consumed by developers who need to use an application to execute and monitor tasks.

Base URI: /sap/hana/im/api/v1

Permissions: In addition to the normal Web IDE user permissions, administrators must grant the SAP HANA role sap.hana.im.api.roles::Execute to users.

Authentication: The GET methods require basic authentication in the Request Header. The XS engine on HANA handles the authentication. No special roles are required.

The POST, PUT, and DELETE methods require the presence of session cookies as well as a X-CSRF token header and value.

You can obtain the X-CSRF-TOKEN value from HANA by looking in the X-CSRF-Token header of the following URL:

HEAD http://<host>:<port>/sap/hana/xs/formLogin/token.xsjs

For more information, see the “Orion-based API to HANA, X-CSRF-Token” topic in the SAP HANA REST API Reference.

Considerations: When executing transactional tasks be aware of the following:

● If providing UTF-8 multi-byte data as part of the taskData in the request body, charset=utf-8 needs to be set in the content – type request header for that multi-byte data to be processed and returned correctly. For example:

content-type = "application/json; charset=utf-8"

● As a result of a JavaScript numeric handling limitation that could result in unintended rounding, values with data types of BIGINT, DOUBLE, or REAL should be provided via the taskData as strings. For these data types, the REST API will return the values in the response body as strings. It will be the responsibility of the client to parse and convert these returned string values into the proper data type.

Other considerations

● Date and time values that are presented by the API reflect the ISO 8601 format which includes both a date and a time (i.e. 2018-01-31T15:30:42.359Z). These date and times represent the local date and time values of the HANA server

● When API calls require passing in data via the request body, the data must be sent in JSON format and the request header content-type needs to be set to 'application/json'. For example:

content-type = "application/json"

Creating virtual tables, modifying property values of virtual tables, or executing tasks that require task data, table types, or parameter values are examples of when values are provided via the request body and would require the presence of the content-type header.

REST API Developer GuideOverview of SAP HANA Smart Data Integration REST API Methods P U B L I C 9

Methods

HTTP/HTTPS Method Action

GET Task information

● GET/tasks [page 11]● GET /tasks/<taskName> [page 13]● GET /tasks/<taskName>/tableTypes [page 15]

Task executions

● GET /tasks/<taskName>/executions [page 20]● GET /tasks/<taskName>/executions/messages [page 22]● GET /tasks/<taskName>/executions/<execId> [page 24]● GET /tasks/<taskName>/executions/<execId>/partitions [page 26]● GET /tasks/<taskName>/executions/<execId>/operations [page 28]● GET /tasks/<taskName>/executions/<execId>/messages [page 29]

Virtual table information

● GET /virtualTables [page 37]● GET /virtualTables/<table> [page 39]● GET /virtualTables/<table>/properties [page 40]

POST Task executions

● POST /tasks/<taskName>/executions [page 16]

Virtual tables

● POST /virtualTables/<table> [page 44]

PUT Task executions

● PUT /tasks/<taskName>/executions [page 31]● PUT /tasks/<taskName>/executions/<execId> [page 34]

Virtual tables

● PUT /virtualTables/<table>/properties [page 42]

DELETE Task executions

● DELETE /tasks/<taskName>/executions [page 33]● DELETE /tasks/<taskName>/executions/<execId> [page 36]

Virtual tables

● DELETE /virtualTables/<table> [page 46]

Related Information

GET/tasks [page 11]GET /tasks/taskName [page 13]GET /tasks/taskName/tableTypes [page 15]POST /tasks/taskName/executions [page 16]


Overview of SAP HANA Smart Data Integration REST API Methods

GET /tasks/taskName/executions [page 20]GET /tasks/taskName/executions/messages [page 22]GET /tasks/taskName/executions/execId [page 24]GET /tasks/ taskName/executions/execId/partitions [page 26]GET /tasks/taskName/executions/execId/operations [page 28]GET /tasks/taskName/executions/execId/messages [page 29]PUT /tasks/ taskName/executions [page 31]DELETE /tasks/taskName/executions [page 33]PUT /tasks/taskName/executions/execId [page 34]DELETE /tasks/taskName/executions/execId [page 36]GET /virtualTables [page 37]GET /virtualTables/table [page 39]GET /virtualTables/table/properties [page 40]PUT /virtualTables/table/properties [page 42]POST /virtualTables/table [page 44]DELETE /virtualTables/table [page 46]

3.1 GET/tasks

Returns a list of available tasks in the catalog of the HANA system to which you are connected. SAP Web IDE package and flowgraph names are used to create task names. For example, <package>::<flowgraph>.

Request

URI: http://<host>:<port>/sap/hana/im/api/v1/tasks

HTTP/HTTPS Method: GET

Permissions: Basic authentication gives you access to tasks and virtual tables based on the permissions that have been granted to you in the SAP HANA catalog. For a task to be presented in the response body, the user must have the SELECT privilege on the task's schema.

Parameters

Name Details Description Type

count Query parameter

Optional

Return the number of available tasks. true or false

Request Example

http://<host>:<port>/sap/hana/im/api/v1/tasks/


You can also use optional query parameters. For example, you can enter the following:

http://<host>:<port>/sap/hana/im/api/v1/tasks?count=true

Response

Format: JSON

Response Status and Error Codes

Code Reason Schema

200 Successful response. ArrayOfTasks[ task { schema: string name: string hasTableTypes: boolean createTime: string(date time ISO 8601) storedProcedure: string runtimeBehavior: string taskType: string ownerName: string } ]

Response Example

[ { "schema": "<schema name>", "name": "<package>::<flowgraph>", "hasTableTypes": false, "createTime": "2016-11-09T16:32:07.818Z", "storedProcedure": "<package>::<stored procedure name>", "runtimeBehavior": "Batch", "taskType": "PLAN", "ownerName": "SYSTEM" }, { "schema": "<schema name>", "name": "<package>::<flowgraph>", "hasTableTypes": true, "createTime": "2016-11-09T16:32:08.308Z", "storedProcedure": "<package>::<stored procedure name>", "runtimeBehavior": "Batch", "taskType": "PLAN", "ownerName": "SYSTEM" }, { "schema": "<schema name>", "name": "<package>::<flowgraph>", "hasTableTypes": false, "createTime": "2016-11-09T16:32:10.026Z", "storedProcedure": "<package>::<stored procedure name>", "runtimeBehavior": "Batch", "taskType": "PLAN", "ownerName": "SYSTEM" } ]



You get the following response when using the count query parameter:

{ "count": 3 }

3.2 GET /tasks/<taskName>

Returns the metadata of a specific task.

Request

URI: http://<host>:<port>/sap/hana/im/api/v1/tasks/<taskName>


Permissions: Basic authentication gives you access to tasks and virtual tables based on the permissions that have been granted to you in the SAP HANA catalog. For task details to be returned, the user must have the SELECT privilege on the task schema. For task table type information to be presented in the response body, the user must have the SELECT privilege on the table type schema.

Parameters


taskName Path parameter

Required

Name of the task for which you want details. You can find task names in the GET/tasks response.

string

schema Query parameter

Optional

Name of the catalog schema that contains the task. This is needed for catalog tasks that are not created through a flowgraph, where tasks with the same name exist in multiple schemas.

string

Request Example

http://<host>:<port>/sap/hana/im/api/v1/tasks/<taskName>

You can also add the optional schema to further identify tasks you are interested in. For example, if you have multiple tasks with the same name, but in different catalog schemas, you can use the schema query parameter to identify which tasks you want.

http://<host>:<port>/sap/hana/im/api/v1/tasks/<taskName>?schema=<schema name>

Response

Format: JSON



Code Reason Schema

200 Successful response. task { schema: string name: string hasTableTypes: boolean createTime: string (date time ISO 8601) storedProcedure: string runTimeBehavior: string taskType: string ownerName: string tableTypesDetails: [] taskParameters: [] }

404 Resource not found.

Response Example

{ "schema": "<schema name>", "name": "<package>::<flowgraph>", "hasTableTypes": true, "createTime": "2016-11-09T16:32:07.818Z", "storedProcedure": "<package>::<name of stored procedure>", "runtimeBehavior": "Batch", "taskType": "PLAN", "ownerName": "SYSTEM", "tableTypesDetails": [ { "name": "<name of the table type>", "schema": "<catalog schema of the table type>", "position": 1, "paramterType": "<IN or OUT table type>", "columns": "<array of columns defined for the table type>" } ],"taskParameters": [ { "name": "variable_name1", "dataType": "varchar", "variableType": "expression", "length": "0", "defaultValue": "'A'" }, { "name": "variable_name2", "dataType": "varchar", "variableType": "expression", "length": "0", "defaultValue": "'A'" } ]}



3.3 GET /tasks/<taskName>/tableTypes

Returns table type information for a particular task.

Request

URI: http://<host>:<port>/sap/hana/im/api/v1/tasks/<taskName>/tableTypes


Permissions: Basic authentication gives you access to tasks and virtual tables based on the permissions that have been granted to you in the HANA catalog. For table type details to be returned, the user must have the SELECT privilege on both the task and table type schemas.

Parameters



Required

Name of the task for which you want the tableTypes. string


Optional

Name of the catalog schema that contains the task. This is needed for catalog tasks that are not created through a flowgraph where tasks with the same name exist in multiple schemas.

string


Optional

Return the count of tableTypes for this task. true or false

Request Example

http://<host>:<port>/sap/hana/im/api/v1/tasks/<taskName>/tableTypes

You can also use the optional schema and/or count parameters. For example, you might enter the following:

http://<host>:<port>/sap/hana/im/api/v1/tasks/<taskName>/tableTypes?count=true&schema=<schema name>

Response

Format: JSON



Code Reason Schema

200 Successful response. Array of tableTypes[ tableType { name: string schema: string position: integer parameterType: string columns: [] } ]

404 Resource not found

Response Example

[ { "position": 1, "schema": "<schema name>", "name": "<package>::<flowgraph>.<table type name>" "parameterType": "IN", "columns": [ { "name": "CID" , "dataType": "INTEGER" , "length": 10 , "scale": null, "nullable": true, "position": 1, "dataTypeId": 4 }, { "name": "CUSTOMERNAME" , "dataType": "NVARCHAR" , "length": 100 , "scale": null, "nullable": true, "position": 2, "dataTypeId": -9 } ] } ]

3.4 POST /tasks/<taskName>/executions

Executes a task.

Request

URI: http://<host>:<port>/sap/hana/im/api/v1/tasks/<taskName>/executions

HTTP/HTTPS Method: POST



Permissions: To be able to execute a task, you need to have the EXECUTE privilege on the task schema. If the task is a transactional task, you will also need the CREATE ANY or CREATE TEMPORARY TABLE privilege on the task schema, as well as the SELECT privilege on the task schema. If the task is a real time task, you will need the ALTER privilege on the task's remote subscription object.

In order to successfully send a POST request, the request header needs to include session cookies as well as the X-CSRF-TOKEN value, which is provided by HANA. For more information about how to obtain this value, see Overview of SAP HANA Smart Data Integration REST API Methods [page 9].

Parameters



Required

Name of the task. string

taskExecutionOptions

Body

OptionalRuntime parameters and data for the execution of a task. Information such as record data for a transactional task, substitution parameters, and table type parameters.

If executing a task that requires providing task data, table types, or parameter values via the request body, these values must be sent in JSON format and the request header content-type needs to be set to 'application/json'. For example:


JSON object

executionParameters { taskParameters: { * } taskData: [ ** taskDataRecord { A JSON object of key-value pairs } ] tableTypeParameters: [ *** ] }


Optional

Name of the catalog schema that contains the task. This is needed for catalog tasks that are not created through a flowgraph.

string

* Name-value pairs of substitution parameters

** Name-value pairs of fields for runtime data

*** String of fully quoted SAP HANA table or view names. The strings in this array must be in the correct sequence so that the value for the first task table type is listed first, the value for the second task table type is listed second, and so on.

Request Example

The body of the request must contain the necessary attributes depending on the task requirements (task parameters, table type parameters, task data, and so on.)

http://<host>:<port>/sap/hana/im/api/v1/tasks/<taskName>/executions


If task parameters, table type parameters, or task data are provided in the request body as part of the task execution, the data must be provided in JSON format and the request header content-type needs to set to 'application/json'. For example:


Response

Format: JSON


Code Reason Schema

201 A running execution of the task was created.

This is what is returned when you execute a task that is not a transactional task.

The taskExecutionId value in the response body is the value to be used for other SAP HANA smart data integration API actions that require the presence of a task execution ID in the URI.

taskExecution { taskExecutionId: integer startTime: string (date time ISO 8601) endTime: string (date time ISO 8601) duration: integer status: string totalProgressPercent: double processedRecords: integer hasSideEffects: boolean userName: string applicationUserName: string messageCount: integer partitions: integer taskParameters: string tableTypeParameters: string }

400 Bad request body error { code: integer message: string }


Response Example

The following example uses taskParameters (the expression and/or scalar parameters are in the flowgraph/task). This task has three task expression parameters:

● ROW_NUM● REGION● LOCALITY

You can see this when requesting the details for the task. The response body for GET /tasks/<taskName> is:

{



"schema": "<schema name>", "name": "<package>::<flowgraph>", "hasTableTypes": false, "createTime": "2016-11-02T14:45:15.780Z", "storedProcedure": "<package>::<stored procedure name>", "runtimeBehavior": "Batch", "taskType": "PLAN", "ownerName": "SYSTEM", "tableTypesDetails": [], "taskParameters": [ { "name": "ROW_NUM", "dataType": "varchar", "variableType": "expression", "length": "0", "defaultValue": "'832'" }, { "name": "LOCALITY", "dataType": "varchar", "variableType": "expression", "length": "0", "defaultValue": "'London'" }, { "name": "REGION", "dataType": "varchar", "variableType": "expression", "length": "0", "defaultValue": "'IL'" } ]}

In the following jQuery example, you would then execute the task and pass in values for the three parameters. Note that since these three parameters have default values (see the following response body), you could leave one or more out of the request body and the REST API will use the default values from the task definition.

var settings = { "async": true, "crossDomain": true, "url": "<host>:<port>/sap/hana/im/api/v1/tasks/<package>::<flowgraph>/executions", "method": "POST", "headers": { "authorization": "Basic c3lzdGVtOm1hbmFnZXI=", "x-csrf-token": "B21142B4DAE21146AC11A5D85F11C78A", "content-type": "application/json;charset=utf-8", "cache-control": "no-cache" }, "data": "{\"taskParameters\" : {\"ROW_NUM\": \"'8'\", \"REGION\":\"'FL'\", \"LOCALITY\":\"'boca'\"}}"}$.ajax(settings).done(function (response) { console.log(response);});

The following is a jQuery example of passing in table type parameters:

var settings = { "async": true, "crossDomain": true, "url": "<host>:<port>/sap/hana/im/api/v1/tasks/<package>::<flowgraph>/executions", "method": "POST", "headers": {


"authorization": "Basic c3lzdGVtOm1hbmFnZXI=", "x-csrf-token": "B21142B4DAE21146AC11A5D85F11C78A", "content-type": "application/json;charset=utf-8", "cache-control": "no-cache" }, "data": "{\"tableTypeParameters\": [\"\\\"<schema name>\\\".\\\"<view>\\\"\",\n \"\\\"EIM_API\\\".\\\"<view>\\\"\"\n \t]\n}" }$.ajax(settings).done(function (response) { console.log(response);});

Related Information

GET /tasks/taskName/executions/execId [page 24]

3.5 GET /tasks/<taskName>/executions

Retrieves all task execution data for a task that has been executed using the SAP HANA smart data integration REST API. For realtime tasks, the full details of the initial load are returned and the delta load tasks are returned in an aggregated summary. For transactional tasks, the REST API returns only the aggregated summary of the task executions.

Request


HTTP/HTTPS Method:GET

Permissions: Basic authentication gives you access to tasks and virtual tables based on the permissions that have been granted to you in the HANA catalog. For task execution information to be returned, the user must have the SELECT privilege on the task schema.

Parameters



Required



Optional

Return the number of executions for the specified task.

true or false

summary Query parameter

Optional

Return summarized task execution information. true or false





Optional


string

Request Example


You can also add optional query parameters. For example, you might enter the following:

http://<host>:<port>/sap/hana/im/api/v1/tasks/<taskName>/executions?count=true&schema=<schema Name>

Response

Format: JSON


Code Reason Schema

200 Successful response What is returned depends on the type of task you execute. The following is an example of a batch task.

The taskExecutionId value in the response body is the value to be used for other SAP HANA smart data integration API actions that require the presence of a task execution ID in the URI.

ArrayOfTaskExecutions[ taskExecution { taskExecutionId: integer startTime: string (date time ISO 8601) endTime: string (date time ISO 8601) duration: integer status: string totalProgressPercent: double processedRecords: integer hasSideEffects: boolean userName: string applicationUserName: string messageCount: integer partitions: integer taskParameters: string tableTypeParameters: string } ]

400 Bad request error { code: integer message: string }


Code Reason Schema


Response Example

[ { "taskExecutionId": 1874, "startTime": "2016-11-04T21:26:00.276Z", "endTime": "2016-11-04T21:26:00.329Z", "duration": 52533, "status": "COMPLETED", "totalProgressPercent": 100, "processedRecords": 19, "hasSideEffects": false, "userName": "<user name>", "applicationUserName": "<user name for the application>", "partitions": 1, "taskParameters": "expr_var01_in1='MX'; expr_var01_in2=lower(\"proj_in\".\"COUNTRY\"); ", "tableTypeParameters": "", "messageCount": 0} ]

Realtime flowgraphs return detailed task execution information for the initial load task as well as a summary response for the delta loads executions. Transactional tasks only return a summarized response.

To retrieve a summarized response for batch tasks, you would enter:

http://<host>:<port>/sap/hana/im/api/v1/tasks/<taskname>/executions?summary=true

The summarized response returns an array of JSON objects (one object for each status found).

[ { "status": "COMPLETED", "count": 24, "processedRecords": 24, "messageCount": 24} ]

3.6 GET /tasks/<taskName>/executions/messages

Returns task execution messages for all task executions. This method is for realtime or transactional tasks because you don't need to monitor individual task executions.

Request

URI: http://<host>:<port>/sap/hana/im/api/v1/tasks/<taskName>/executions/messages




Permissions: Basic authentication gives you access to tasks and virtual tables based on the permissions that have been granted to you in the HANA catalog. For task execution message information to be returned, the user must have the SELECT privilege on the task schema.

Parameters



Required

Name of the task for which you want message information.

string

severity Query parameter

Optional

Severity of the message error, warning or information


Optional

Return the message count. true or false


Optional


string

Request Example

http://<host>:<port>/sap/hana/im/api/v1/tasks/<taskName>/executions/messages

You can also add the optional count query parameter:

http://<host>:<port>/sap/hana/im/api/v1/tasks/<taskName>/executions/messages?count=true

Response

Format: JSON


Code Reason Schema

200 Successful response. Task execution messages[ taskMessages { taskExecutionID: integer operationName: string severity: string messageId: string messageText: string } ]


Code Reason Schema



Response Example

[ { taskExecutionId:<task execution id number>, operationName: "<operation name>", severity: "ERROR", messageId: "ABC000", messageText: "Error message text" }, { taskExecutionId:<task execution id number>, operationName: "<operation name>", severity: "ERROR", messageId: "XYZ000", messageText: "Error message text" }]

3.7 GET /tasks/<taskName>/executions/<execId>

Gets task execution details for a single task execution.

Request

URI: http://<host>:<port>/sap/hana/im/api/v1/tasks/<taskName>/executions/<execId>

The value to be substituted for <execId> is the specific taskExecutionId value for an executed task. This taskExecutionId value is presented in the response body when executing a task or when requesting information for all executions for a particular task.


Permissions: Basic authentication gives you access to tasks and virtual tables based on the permissions that have been granted to you in the HANA catalog. For task execution information to be returned, the user must have the SELECT privilege on the task schema.

Parameters





Required

Name of the task for which you want details. string

execId Path parameter

Required

Task execution ID. integer


Optional


string

Request Example

http://<host>:<port>/sap/hana/im/api/v1/tasks/<taskName>/executions/<execId>

Response

Format: JSON


Code Reason Schema

200 Successful response.

taskExecution { taskExecutionId: integer startTime: string (date time ISO 8601) endTime: string (date time ISO 8601) duration: integer status: string totalProgressPercent: double processedRecords: integer hasSideEffects: boolean userName: string applicationUserName: string messageCount: integer partitions: integer taskParameters: string tableTypeParameters: string }


Response Example

{ taskExecutionId: 1874, startTime: "2016-11-04T21:26:00.276Z", endTime: "2016-11-04T21:26:00.329Z", duration: 52533, status: "COMPLETED", totalProgressPercent: 100, processedRecords: 19, hasSideEffects: false, userName:<user name> , applicationUserName: <user name for the application>,


partitions: 1, taskParameters: "", tableTypeParameters: "" messageCount: 0 }

Related Information

POST /tasks/taskName/executions [page 16]

3.8 GET /tasks/ <taskName>/executions/<execId>/partitions

Get task execution partition information.

Request

URI: http://<host>:<port>/sap/hana/im/api/v1/tasks/<taskName>/executions/<execId>/partitions



Permissions: Basic authentication gives you access to tasks and virtual tables based on the permissions that have been granted to you in the HANA catalog. For task partition information to be returned, the user must have the SELECT privilege on the task schema.

Parameters



Required



Required



Optional


string



Request Example

http://<host>:<port>/sap/hana/im/api/v1/tasks/<taskName>/executions/<execId>/partitions

Response

Format: JSON


If the _task_execute_remaining_partitions_since_execution_id built-in variable of a flowgraph (task) is being used for executing partitions, it is the partitionTaskExecutionId value that needs to be passed in for the variable (not the taskExecutionId value that is used in the URL of this request. )

Code Reason Schema

200 Successful response. Task execution partitions[ taskPartitions { partitionId: integer partitionName: string startTime: string (date time ISO 8601) endTime: string (date time ISO 8601) duration: integer status: string processedRecords: integer totalProgressPercent: double partitionTaskExecutionId: integer } ]


Response Example

[ { partitionId: <partition ID>, partitionName: "<name of partition>", startTime: "2016-11-04T21:26:00.276Z", endTime: "2016-11-04T21:26:00.329Z", duration: 52533, status: "COMPLETED", processedRecords: 19, totalProcessPercent: 100 partitionTaskExecutionID: 45674 } ]


3.9 GET /tasks/<taskName>/executions/<execId>/operations

Returns operation level details for a particular task execution.

Request

URI: http://<host>:<port>/sap/hana/im/api/v1/tasks/<taskName>/executions/<execId>/operations



Permissions: Basic authentication gives you access to tasks and virtual tables based on the permissions that have been granted to you in the SAP HANA catalog. For task execution operation information to be returned, the user must have the SELECT privilege on the task schema.

Parameters



Required



Required



Optional


string

Request Example

http://<host>:<port>/sap/hana/im/api/v1/tasks/<taskName>/executions/<execId>/operations

Response

Format: JSON




Code Reason Schema

200 Successful response. Task execution operations[ taskOperation { operationName: string scenarioOpName: string operationType: string startTime: string (date time ISO 8601) endTime: string (date time ISO 8601) duration: integer status: string processedRecords: integer operationProgressPercent: double hasSideEffects: boolean transactionId: integer partitionId: integer }]


Response Example

[ { operationName: <name of the operation>, scenarioOpName: <calc scenario node operation name>, operationType: "PROJECTION", startTime: "2016-11-04T21:26:00.276Z", endTime: "2016-11-04T21:26:00.329Z", duration: 40184, status: "COMPLETED", processedRecords: 100891, operationProgressPercent: 100, hasSideEffects: false, transactionId: 34 partitionId: 1 } ]

3.10 GET /tasks/<taskName>/executions/<execId>/messages

Returns runtime messages associated with a task execution.

Request

URI: http://<host>:<port>/sap/hana/im/api/v1/tasks/<taskName>/executions/<execId>/messages




Permissions: Basic authentication gives you access to tasks and virtual tables based on the permissions that have been granted to you in the SAP HANA catalog. For task execution message information to be returned, the user must have the SELECT privilege on the task schema.

Parameters



Required



Required


severity Query parameter

Optional

Severity of the message. error, warning or information


Optional

The message count. true or false


Optional


string

Request Example

http://<host>:<port>/sap/hana/im/api/v1/tasks/<taskName>/executions/<execId>/messages

You can also add the optional query parameters:

http://<host>:<port>/sap/hana/im/api/v1/tasks/<taskName>/executions/<execId>/messages?count=true&severity=<severity type>

Response

Format: JSON




Code Reason Schema

200 Successful response. Task execution messages[ taskMessages { operationName: string severity: string messageId: string messageText: string }]



Response Example

[ { operationName: "<operation name>", severity: "ERROR", messageId: "ABC000", messageText: "Error message text"},{ operationName: "<operation name>", severity: "ERROR", messageId: "XYZ000", messageText: "Error message text"}]

3.11 PUT /tasks/ <taskName>/executions

Cancels the execution of a realtime flowgraph. This method works for realtime flowgraphs only because batch uses an execution ID. Canceling a real time flow graph also resets the remote subscription

Request


HTTP/HTTPS Method: PUT

Permissions: To cancel a task, you either must be the user that started the task or you must have the SESSION ADMIN system privilege. If the task is a real time task, you must have SELECT or EXECUTE on the task schema as well as the ALTER privilege on the task's remote subscription object.


In order to successfully send a PUT request, the request header needs to include session cookies as well as the X-CSRF-TOKEN value, which is provided by HANA. For more information about how to obtain this value, see Overview of SAP HANA Smart Data Integration REST API Methods [page 9].

Parameters



Required


waitTime Query parameter

Optional

Time in seconds to wait for task to cancel before returning. (Default is 0.)

integer


Optional


string

Request Example


Response

Format: JSON


Code Reason Schema

200 Successful response. taskExecution { taskExecutionId: integer startTime: string (date time ISO 8601) endTime: string (date time ISO 8601) duration: integer status: string totalProgressPercent: double processedRecords: integer hasSideEffects: boolean userName: string applicationUserName: string messageCount: integer partitions: integer taskParameters: string tableTypeParameters: string } }




3.12 DELETE /tasks/<taskName>/executions

Deletes all task execution data for a specific task.

Request


HTTP/HTTPS Method: DELETE

Permissions: For task execution information to be deleted, the user must have the SELECT privilege on the task schema.

In order to successfully send a DELETE request, the request header needs to include session cookies, as well as the X-CSRF-TOKEN value, which is provided by SAP HANA. For more information about how to obtain this value, see Overview of SAP HANA Smart Data Integration REST API Methods [page 9].

Parameters



Required


retention Query parameter

Optional

Retention period for task execution data (in seconds). All data that is older than this value is deleted.

integer-- time in seconds. Delete all data older than this value, Default 0.


Optional


string

Request Example


Response

Format: JSON


Code Reason Example



Code Reason Example

400 Bad request

You would get this code if you attempt to delete task execution information for a task that resides in multiple schemas.

error { code: integer message: string }


3.13 PUT /tasks/<taskName>/executions/<execId>

Cancels a running batch task execution.

If the task execution is no longer running when the canceling of the task is attempted, the response body will include the details of the task execution.

Request




Permissions: To cancel a task, you either must be the user that started the task or you must have the SESSION ADMIN system privilege.

In order to successfully send a PUT request, the request header needs to include session cookies, as well as the the X-CSRF-TOKEN value, which is provided by HANA. For more information about how to obtain this value, see Overview of SAP HANA Smart Data Integration REST API Methods [page 9].

Parameters



Required



Required


waitTime Query parameter

Optional

Time in seconds to wait for task to cancel before returning (default is 0).

integer





Optional


string

Request Example


Response

Format: JSON


Code Reason Schema

200 Successful task cancellation. taskExecution { taskExecutionId: integer,

startTime: string (date time ISO 8601) endTime: string (date time ISO 8601) duration: integer status: string totalProgressPercent: double processedRecords: integer hasSideEffects: boolean, userName: string, applicationUserName: string, partitions: integer, taskParameters: string, tableTypeParameters: string, messageCount: integer }

400 Bad Request error { code: integer message: string }



3.14 DELETE /tasks/<taskName>/executions/<execId>

Deletes task execution details for a single task execution.

Request




Permissions: For task execution information to be deleted, you must have the SELECT privilege on the task schema.

In order to successfully send a DELETE request, the request header needs to include session cookies, as well as the X-CSRF-TOKEN value, which is provided by HANA. For more information about how to obtain this value, see Overview of SAP HANA Smart Data Integration REST API Methods [page 9].

Parameters



Required



Required



Optional


string

Request Example


Response

Format: JSON




Code Reason

204 Successful deletion.

404 Resource not found.

3.15 GET /virtualTables

Returns a list of all registered virtual tables.

Request

URI: http://<host>:<port>/sap/hana/im/api/v1/virtualTables


Permissions: Basic authentication gives you access to tasks and virtual tables based on the permissions that have been granted to you in the SAP HANA catalog. For a virtual table to be presented in the response body, the user must have the CREATE VIRTUAL TABLE privilege on the table's remote source.

Parameters



Optional

Return the number of available virtual tables.

true or false

Request Example

http://<host>:<port>/sap/hana/im/api/v1/virtualTables

You can also add the optional count query parameter:

http://<host>:<port>/sap/hana/im/api/v1/virtualTables?count=true

Response

Format: JSON



Code Reason Schema

200 Successful response. ArrayOfVirtualTables[virtualTable { schema: string name: string remoteSource: string remoteObject: string remoteOwner: string remoteDb: string isInsertable: boolean isUpdatable: boolean isDeletable: boolean isUpsertable: boolean isSelectable: boolean isRemoteSubscriptionSupported: boolean isRemoteSubscriptionTransactional: boolean} ]

Response Example

[ { "schema": "<schema name>", "name": "<name of the virtual table>", "remoteSource": "XXX_API_REMOTE_SOURCE", "remoteDb": "<NULL>", "remoteOwner": "<NULL>", "remoteObject": "\"XXX_XXX_REMOTE\".\"XXX_API_INITIAL_LOAD\"", "isInsertable": true, "isUpdatable": true, "isDeletable": true, "isUpsertable": false, "isSelectable": true, "isRemoteSubscriptionSupported": true, "isRemoteSubscriptionTransactional": true }, { "schema": "<schema name>", "name": "<name of the virtual table>", "remoteSource": "XXX_API_REMOTE_SOURCE", "remoteDb": "<NULL>", "remoteOwner": "<NULL>", "remoteObject": "\"XXX_API_REMOTE\".\"XXX_API_REALTIME_OUTPUT\"", "isInsertable": true, "isUpdatable": true, "isDeletable": true, "isUpsertable": false, "isSelectable": true, "isRemoteSubscriptionSupported": true, "isRemoteSubscriptionTransactional": true } ]

If you use the count query parameter, this is the response you would see:

{ "count": 2 }



3.16 GET /virtualTables/<table>

Returns details allowing you to further identify a particular virtual table. For example, if there is a virtual table named CONTACTS in schema A and a virtual table named CONTACTS in schema B, then you will need to specify the schema in order to correctly identify the correct table named CONTACTS for which you are looking.

Request

URI: http://<host>:<port>/sap/hana/im/api/v1/virtualTables/<table>


Permissions: Basic authentication gives you access to tasks and virtual tables based on the permissions that have been granted to you in the SAP HANA catalog.

For a virtual table's details to be presented in the response body, the user must have the CREATE VIRTUAL TABLE privilege on the table's remote source.

Parameters


table Path parameter

Required

Name of the virtual table. string


Optional

Catalog schema.

NoteRequired if the virtual table name exists in more than one schema.

string

Request Example

http://<host>:<port>/sap/hana/im/api/v1/virtualTables/<table>

You can also add the optional schema query parameter to further identify virtual tables you are interested in. Similar to what was discussed in the above example, if you have multiple virtual tables with the same name, but in different catalog schemas, the schema needs to be provided.

http://<host>:<port>/sap/hana/im/api/v1/virtualTables/<table>?schema=<schema name>

Response

Format: JSON



Code Reason Schema

200 Successful response virtualTable { schema: string name: string remoteSource: string remoteObject: string remoteOwner: string remoteDb: string isInsertable: boolean isUpdatable: boolean isDeletable: boolean isUpsertable: boolean isSelectable: boolean isRemoteSubscriptionSupported: boolean isRemoteSubscriptionTransactional: boolean}


Response Example

{ "schema": "<schema name>", "name": "<name of the virtual table>", "remoteSource": "XXX_API_REMOTE_SOURCE", "remoteObject": "\"XXX_API_REMOTE\".\"XXX_API_INITIAL_LOAD\"", "remoteOwner": "<NULL>", "remoteDb": "<NULL>", "isInsertable": true, "isUpdatable": true, "isDeletable": true, "isUpsertable": false, "isSelectable": true, "isRemoteSubscriptionSupported": true, "isRemoteSubscriptionTransactional": true }

3.17 GET /virtualTables/<table>/properties

Retrieves property information for a specific virtual table.

Request

URI: http://<host>:<port>/sap/hana/im/api/v1/virtualTables/<table>/properties


Permissions: Basic authentication gives you access to tasks and virtual tables based on the permissions that have been granted to you in the SAP HANA catalog. For virtual table properties to be presented in the response body, the user must have the CREATE VIRTUAL TABLE privilege on the table's remote source.

Parameters





Required

Name of the virtual table string


Optional

Catalog schema


string

column Query parameter

Optional

If present, returns column properties for the specified column name

string

Request Example

http://<host>:<port>/sap/hana/im/api/v1/virtualTables/<table>/properties

You can also add the optional schema query parameter, if the virtual table name exists in more than one schema:

http://<host>:<port>/sap/hana/im/api/v1/virtualTables/<table>/properties?schema=<schema name>

To request column properties for a virtual table column:

http://<host>:<port>/sap/hana/im/api/v1/virtualTables/<table>/properties?column=<column name>

Response

Format: JSON


Code Reason Schema

200 Successful response. virtual table properties { }

400 Bad Request (If table name exists in multiple schemas)


Response Example

{ "property1" : "value1","property2" : "value2","property3" : "value3"


}

3.18 PUT /virtualTables/<table>/properties

Modifies the properties of an existing virtual table.

Request

URI: http://<host>:<port>/sap/hana/im/api/v1/virtualTables/<table>/properties


Permissions: To modify a virtual table, you must have the CREATE VIRTUAL TABLE privilege on the table's remote source, as well as the ALTER privilege on the schema of the virtual table being modified.

In order to successfully send a PUT request, the request header needs to include session cookies, as well as the X-CSRF-TOKEN value, which is provided by HANA. For more information about how to obtain this value, see Overview of SAP HANA Smart Data Integration REST API Methods [page 9].

When setting and un-setting virtual table properties via the request body, these changes to the properties must be sent in JSON format and the request header content-type needs to be set to 'application/json'. For example:


Parameters



Required



Optional

Name of the catalog schema that contains the virtual table. This can be set to values that reflect valid schemas that exist on the HANA instance.


string

set Query parameter

Required

Lets you set and unset virtual table properties. string (SET or UNSET)

column Query parameter

Optional

When used in conjunction with the set parameter, it lets you set and unset virtual table column properties.

string

Request Example

http://<host>:<port>/sap/hana/im/api/v1/virtualTables/<table>/properties



The request header needs to include the content type value. For example:


To set values for two properties named property1 and property2:

http://<host>:<port>/sap/hana/im/api/v1/virtualTables/<table>/properties?set=set

Request body example:

{ "properties" : ["property1=value1", "property2=value2"] }

To unset two properties named property1 and property2:

http://<host>:<port>/sap/hana/im/api/v1/virtualTables/<table>/properties?set=unset

Request body example:

{ "properties" : ["property1", "property2"] }

Response

Format: JSON


Code Reason


A success response will return an object that includes the virtual table properties. For example something like:

virtual table properties { "<virtual table property name>": "<virtual table property value>", "<virtual table property name>": "<virtual table property value>", "<virtual table property name>": "<virtual table property value>" }

400 Bad Request (If table name exists in multiple schemas)

404 Response not found


3.19 POST /virtualTables/<table>

Creates a virtual table.

Request


HTTP/HTTPS Method: POST

Permissions: To create a virtual table, you must have the CREATE VIRTUAL TABLE privilege on the table's remote source, as well as the CREATE ANY privilege on the schema of the virtual table to be created.

In order to successfully send a POST request, the request header needs to include session cookies as well as the X-CSRF-TOKEN value, which is provided by SAP HANA. For more information about how to obtain this value, see Overview of SAP HANA Smart Data Integration REST API Methods [page 9].

When creating virtual tables, the remote object information necessary to create the table is provided via the request body. The request body must be sent in JSON format and the request header content-type needs to be set to application/json. For example:


Parameters



Required

Name of virtual table string


Optional

The catalog schema string

Request Example


You can also add the optional schema query parameter:

http://<host>:<port>/sap/hana/im/api/v1/virtualTables/<table>?schema=<schema name>

When creating virtual tables, remote source information must be provided in the request body in JSON format. For example:

{ "remoteSource": "<Remote Source Name>", "remoteDb": "<Remote Db Name>", "remoteOwner": "<Remote Source Owner>", "remoteObject": "<Remote Source Object>" };



where each of the values provided above reflects the necessary remote component required for creating the virtual table. Providing a remoteSource and remoteObject key/value pair is always required where providing a remoteDb and/or remoteOwner will be dependent upon the remote source type that is being used for creating the virtual table.

Response

Format: JSON


Code Reason Schema

201 Created the virtual table

virtualTable { schema: string name: string remoteSource: string remoteObject: string remoteOwner: string remoteDb: string isInsertable: boolean isUpdatable: boolean isDeletable: boolean isUpsertable: boolean isSelectable: boolean isRemoteSubscriptionSupported: boolean isRemoteSubscriptionTransactional: boolean}

400 Bad Request (If attempting to create a virtual table using a request body that doesn't contain the necessary remote object information)


409 Conflict (If attempting to create a virtual table that already exists)

Response Example

{ "schema": "<schema name>", "name": "<name of the virtual table>", "remoteSource": "XXX_API_REMOTE_SOURCE", "remoteObject": "\"XXX_API_REMOTE\".\"XXX_API_INITIAL_LOAD\"", "remoteOwner": "<NULL>", "remoteDb": "<NULL>", "isInsertable": true, "isUpdatable": true, "isDeletable": true, "isUpsertable": false, "isSelectable": true, "isRemoteSubscriptionSupported": true, "isRemoteSubscriptionTransactional": true


}

3.20 DELETE /virtualTables/<table>Deletes a virtual table from the catalog.

Request



Permissions: To delete a virtual table, you must have the CREATE VIRTUAL TABLE privilege on the table's remote source, as well as the DROP privilege on the schema of the virtual table. For dependent objects to be dropped, the user must have created the dependent objects.

In order to successfully send a DELETE request, the request header needs to include session cookies, as well as the X-CSRF-TOKEN value, which is provided by HANA. For more information about how to obtain this value, see Overview of SAP HANA Smart Data Integration REST API Methods [page 9].

Parameters



Required



Optional

Catalog schema. (Required if the virtual table name exists in more than one schema).

string

dropOptions Query parameter

Optional

Table drop options. string -- RESTRICT or CASCADE, Default is CASCADE.

cascade drops the virtual table and dependent objects while restrict will drop the virtual table only when dependent objects do not exist.

Request Example


Response

Format: JSON




Code Reason

204 No content

404 The virtual table specified cannot be found.


Important Disclaimers and Legal Information

HyperlinksSome links are classified by an icon and/or a mouseover text. These links provide additional information.About the icons:

● Links with the icon : You are entering a Web site that is not hosted by SAP. By using such links, you agree (unless expressly stated otherwise in your agreements with SAP) to this:

● The content of the linked-to site is not SAP documentation. You may not infer any product claims against SAP based on this information.● SAP does not agree or disagree with the content on the linked-to site, nor does SAP warrant the availability and correctness. SAP shall not be liable for any

damages caused by the use of such content unless damages have been caused by SAP's gross negligence or willful misconduct.

● Links with the icon : You are leaving the documentation for that particular SAP product or service and are entering a SAP-hosted Web site. By using such links, you agree that (unless expressly stated otherwise in your agreements with SAP) you may not infer any product claims against SAP based on this information.

Beta and Other Experimental FeaturesExperimental features are not part of the officially delivered scope that SAP guarantees for future releases. This means that experimental features may be changed by SAP at any time for any reason without notice. Experimental features are not for productive use. You may not demonstrate, test, examine, evaluate or otherwise use the experimental features in a live operating environment or with data that has not been sufficiently backed up.The purpose of experimental features is to get feedback early on, allowing customers and partners to influence the future product accordingly. By providing your feedback (e.g. in the SAP Community), you accept that intellectual property rights of the contributions or derivative works shall remain the exclusive property of SAP.

Example CodeAny software coding and/or code snippets are examples. They are not for productive use. The example code is only intended to better explain and visualize the syntax and phrasing rules. SAP does not warrant the correctness and completeness of the example code. SAP shall not be liable for errors or damages caused by the use of example code unless damages have been caused by SAP's gross negligence or willful misconduct.

Gender-Related LanguageWe try not to use genderspecific word forms and formulations. As appropriate for context and readability, SAP may use masculine word forms to refer to all genders.

Videos Hosted on External PlatformsSome videos may point to third-party video hosting platforms. SAP cannot guarantee the future availability of videos stored on these platforms. Furthermore, any advertisements or other content hosted on these platforms (for example, suggested videos or by navigating to other videos hosted on the same site), are not within the control or responsibility of SAP.


Important Disclaimers and Legal Information

REST API Developer GuideImportant Disclaimers and Legal Information P U B L I C 49

www.sap.com/contactsap

© 2020 SAP SE or an SAP affiliate company. All rights reserved.

No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP SE or an SAP affiliate company. The information contained herein may be changed without prior notice.

Some software products marketed by SAP SE and its distributors contain proprietary software components of other software vendors. National product specifications may vary.

These materials are provided by SAP SE or an SAP affiliate company for informational purposes only, without representation or warranty of any kind, and SAP or its affiliated companies shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP or SAP affiliate company products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.

SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE (or an SAP affiliate company) in Germany and other countries. All other product and service names mentioned are the trademarks of their respective companies.

Please see https://www.sap.com/about/legal/trademark.html for additional trademark information and notices.

THE BEST RUN

https://www.sap.com/about/legal/trademark.html

REST API Developer Guide

Documents

Transcript of REST API Developer Guide