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 technicaly 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.
Contents
- 1 Actions on Workspaces
- 2. Actions on Projects
- 3. Using Mustache Templates
- 4. Create Application Support
Actions on workspaces
List all Available Workspaces
Obtain the list of available workspaces (http://wiki.eclipse.org/Orion/Server_API/Workspace_API#Getting_the_list_of_available_workspaces).
Example Request
GET /sap/hana/xs/dt/base/workspace
EclipseWeb-Version: 1.0
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 132
ETag: "1"
{
"UserName": "Sam",
"Id": "987fd076g5sd6",
"Workspaces": [{ "Id" : "SAM_My_Dev_workspace_0", "Location" : "http://example.com/sap/hana/xs/dt/base/file/sap/hana/xs/dt/base/workspace/SAM_My_Dev_workspace_0", "LastModified" : 1291907325193", "Name" : "My Dev Workspace" }]
}
Create a Workspace
Create a new workspace.
Based on: http://wiki.eclipse.org/Orion/Server_API/Workspace_API#Creating_a_workspace
Example Request
POST sap/hana/xs/dt/base/workspace
EclipseWeb-Version: 1.0
X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"
Slug: My Dev Workspace
Example Response
HTTP/1.1 201 Created
Location: [http://example.com/sap/hana/xs/dt/base/file/sap/hana/xs/dt/base/content/workspace/SAM_My_Dev_workspace_0]
ETag: "1"
Content-Type: application/json
{
"Id": "SAM_My_Dev_workspace_0",
"Name": "My Dev Workspace",
"Location": "http://example.com/sap/hana/xs/dt/base/file/sap/hana/xs/dt/base/content/workspace/SAM_My_Dev_workspace_0",
"Projects": [],
"Children": []
}
Display Workspace Metadata
Retrieve metadata about a specified workspace.
Based on: http://wiki.eclipse.org/Orion/Server_API/Workspace_API#Getting_workspace_metadata
Example Request
GET sap/hana/xs/dt/base/workspace/SAM_My_Dev_workspace_0
EclipseWeb-Version: 1.0
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 132
ETag: "33"
{
"Id" ; "SAM_My_Dev_workspace_0",
"Name": "My Dev Workspace",
"Projects":
[{ "Id" : "SAM_My_Dev_Workspace_0My_Project_AA", "Location" : "http://example.com/sap/hana/xs/dt/base/file/SAM_My_Dev_Workspace_0/SAM_My_Dev_Workspace_0_My_Project_AA" }],
"Children":
[{ "Name" : "My Project AA", "Location" : "http://example.com/sap/hana/xs/dt/base/file/SAM_My_Dev_workspace_0/SAM_My_Dev_Workspace_0_My_Project_AA", "Children-Location" : "http://example.com/sap/hana/xs/dt/base/file/SAM_My_Dev_workspace_0/SAM_My_Dev_Workspace_0_My_Project_AA?depth=1", "Directory" : true }]
}
Change Workspace Metadata
Change workspace metadata.
Based on: http://wiki.eclipse.org/Orion/Server_API/Workspace_API#Changing_workspace_metadata
Example Request
PUT /sap/hana/xs/dt/base/workspace/SAM_My_Dev_Workspace_0
X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"
{
"Name" : "My Dev Workspace Update",
}
Example Response
HTTP/1.1 204 OK
Delete a Workspace
Delete an existing workspace. Note that deleting a non-existent workspace has no effect.
Based on http://wiki.eclipse.org/Orion/Server_API/Workspace_API#Deleting_a_workspace
Example Request
DELETE /sap/hana/xs/dt/base/workspace/SAM_My_Dev_Workspace_0
X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"
Example Response
HTTP/1.1 204 OK
Actions on Projects
Add a Project to a Workspace
Add a project to an existing workspace. If the project does not already exist it will be created.You can create an ORION project or an SAP HANA XS project as described in the respective section.
Based on: http://wiki.eclipse.org/Orion/Server_API/Workspace_API#Add_a_project_to_a_workspace
2.1.1. Create an ORION Native Project
Create the project as an SAP HANA XS subpackage in the specified workspace package; it is not an SAP HANA XS application package. The project is assigned to the projects list in the workspace metadata.
Example Request
POST /sap/hana/xs/dt/base/workspace/SAM_My_Dev_workspace_0
X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"
EclipseWeb-Version: 1.0
Slug: "My Project"
Example Response
HTTP/1.1 201 OK
Location: [http://localhost:8080/sap/hana/xs/dt/base/file/SAM_My_Dev_workspace_0/My Project]
{
"Id": "SAM_My_Dev_Workspace_0_My_Project_0",
"Location": "http://localhost:8080/sap/hana/xs/dt/base/file/sap/hana/xs/dt/base/content/workspace/SAM_My_Dev_Workspace_0/My Project",
"ContentLocation": "http://localhost:8080/sap/hana/xs/dt/base/file/sap/hana/xs/dt/base/content/workspace/SAM_My_Dev_Workspace_0/My Project",
"Name": "My Project"
}
2.1.2 Create an SAP HANA XS Project at a Specified Location and assign it to a Workspace
Create the project as an SAP HANA XS subpackage in the specified location; it is an SAP HANA XS application package. The project is assigned to the projects list in the workspace metadata.
Note that the method described in this section is not part of the current ORION API specification.
Example Request
// Triggering SAP extension
oSapBackPack = new Object();
strProjectName = "My Project" ;
oSapBackPack.isXSProject = true;
oSapBackPack.xsProjectLocation = "/content";
sapBackPack = JSON.stringify(oSapBackPack);
POST /sap/hana/xs/dt/base/workspace/SAM_My_Dev_Workspace_0
X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"
EclipseWeb-Version: 1.0
Slug: "My Project"
SapBackPack: "{"isXSProject": 'true', "xsProjectLocation":'/content'}"
Example Response
HTTP/1.1 201 OK
Location: [http://localhost:8080/sap/hana/xs/dt/base/file/content/My Project]
{
"Id": "SAM_My_Dev_Workspace_0_My_Project_0",
"Location": "http://localhost:8080/sap/hana/xs/dt/base/file/content/My_Project",
"ContentLocation": "http://localhost:8080/sap/hana/xs/dt/base/file/content/My_Project",
"Name": "My Project"
}
2.1.3 Create an SAP HANA XS Project in a Specified Location, Which is Not Visible in the ORION Workspace
Create the project as an SAP HANA XS subpackage in the specified location; it is not an SAP HANA XS application package. The project is not assigned to the projects list in the workspace metadata.
This method for creating a new project is not part of the current ORION API specification.
Example Request
// Triggering SAP extension
oSapBackPack = new Object();
strProjectName = "My Project" ;
oSapBackPack.isXSProject = true;
oSapBackPack.xsProjectLocation = "/content";
sapBackPack = JSON.stringify(oSapBackPack);
POST /sap/hana/xs/dt/base/workspace
X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"
EclipseWeb-Version: 1.0
Slug: "My Project"
SapBackPack: "{"isXSProject": 'true', "xsProjectLocation":'/content'}"
Example Response
HTTP/1.1 201 OK
Location: [http://localhost:8080/sap/hana/xs/dt/base/file/content/My Project]
{
"Id": "My_Project_0",
"Location": "http://localhost:8080/sap/hana/xs/dt/base/file/content/My Project",
"ContentLocation": "http://localhost:8080/sap/hana/xs/dt/base/file/content/My Project",
"Name": "My Project"
}
Moving (Renaming) a Project
Move an existing project to a new location.
Based on: http://wiki.eclipse.org/Orion/ServerAPI/Workspace_API#Moving.28renaming.29_a_project
Example Request
POST /sap/hana/xs/dt/base/workspace/SAM_My_Dev_workspace_0
X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"
Orion-Version: 1.0
Content-Length: 144
Content-Type: application/json
Slug: "destinationProject"
X-Create-Options: move
{
"Location": "http://example.com/sap/hana/xs/dt/base/file/SAM_My_Dev_workspace_0/destinationProject"
}
Example Response
HTTP/1.1 200 OK
Location: [http://example.com/sap/hana/xs/dt/base/file/SAM_My_Dev_workspace_0/destinationProject]
ETag: "1"
Content-Type: application/json
{
"ContentLocation": "//example.com/sap/hana/xs/dt/base/file/content/destinationProject",
"Id": "SAM_My_Dev_workspace_0_destinationProject_0",
"Location": "/sap/hana/xs/dt/base/file/content/destinationProject",
"Name": "destinationProject"
}
Remove a Project from a Workspace
Remove an existing project from a workspace. It removes the project reference from the workspace metadata but leaves the project itself in the repository. This method is based on http://wiki.eclipse.org/Orion/Server_API/Workspace_API#Remove_a_project_from_a_workspace. To remove the project (with all its content) from the repository, use either the File API or the method described in 2.4.Remove a project including content.
Example Request
DELETE /sap/hana/xs/dt/base/workspace/SAM_My_Dev_workspace_0/SAM_My_Dev_workspace_0_My_Project_0
X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"
Example Response
HTTP/1.1 204 OK
Remove a Project Including Content
Remove an existing project from a workspace including its content. Package and content are physically deleted. This method is not part of the current ORION SERVER API specification.
Example Request
// Triggering SAP extension
strProjectName = "My_Project_0" ;
var oSapBackPack = new Object();
oSapBackPack.isXSProject = true;
oSapBackPack.xsDeleteLocation = "/content/"+ strProjectName ;
var sapBackPack = JSON.stringify(oSapBackPack);
DELETE /sap/hana/xs/dt/base/workspace/SAM_My_Dev_workspace_0/SAM_My_Dev_workspace_0_My_Project_0
X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"
SapBackPack: {"isXSProject":'true', "xsDeleteLocation":'/content/My_Project_0'}
Example Response
HTTP/1.1 204 OK
Using Mustache Templates
This part of the REST API provides functionaliy that enables you to use so-called "mustache" templates in your implementation. Mustache templates enable you to create any kind of text-based, reusable components in the context of your tool, for example, to support the generation of project-specific files and pacakage layouts. This includes project-specific naming during the creation of a new project instance.
getProjectArtifactTemplate
Provides the complete list of template descriptions for a specific project.
Example Request
var strServiceName = "getProjectArtifactTemplate";
var strSapBackPack = "{\"projectType\":\"XS\",\"isTemplateContentRequired\":true}";
var request = new $.net.http.Request($.net.http.GET, strExecPathTemplate);;
request.headers.set('Service-Name', strServiceName);
request.headers.set('SapBackPack', strSapBackPack);
var response = client.request(request, destination).getResponse();
Input and Output Input
Name | mandatory | Description |
---|---|---|
projectType | Y | XS (future possibilities: DB,RIVER) |
projectLocation [1] | Y | Project's full package name |
isTemplateContentRequired | Y | true: Template content returned |
JSON
{
"projectType": "XS",
"projectLocation": "/sap/hana/xs/myproject",
"isTemplateContentRequired": false
}
Output
The output returned is an array of entries whose format is described in the code block below The response is formatted as a JSON string, which can be directly instantiated into a JavaScript object using the JSON.parse
method or tranformed into an object instance of the consuming runtime. The information displayed in the following table describes the structure of the returned array:
Name | mandatory | Description |
---|---|---|
List | Y | Project's artifacts list with related content |
type [a] | Y | Artifact type (file suffix) |
subType [a] | Artifact sub type (for example, Modification Exit for XSOData) | |
name [b] | Y | Artifact name (for label) |
groupName [2],[a]or[b] | Y | Artifact group name |
desc [b] | Y | Artifact description (for tooltip) |
isExist [3],[a] | Y | Artifact already exists |
isMandatory [a] | Y | Artifact mandatory indicator |
isRecommended [a] | Y | Artifact recommended indicator |
version [b] | Y | Artifact version (compatibility indicator for client-side) |
List | Y | Artifact template parameters for template instantiation |
name | Y | Artifact template parameter name |
defaultVal | Artifact template parameter default value | |
desc | Y | Artifact template parameter description (for tooltip) |
templateContent [4],[c] | Artifact template content |
JSON
{
"artifact": [
{
"type": "xsodata",
"subType": "modificationExit",
"name": "OData descriptor",
"groupName": "XS",
"isMandatory": false
"isRecommended": false
"desc": "OData descriptor with Modification Exit",
"version": 1,
"templateParam": [
{
"name": "artifactName",
"defaultVal": "",
"desc": "Artifact name"
}
],
"templateContent": ""
}
]
}
Note the following:
[1] projectLocation
: the place where the project will be created. The server uses this information to check artifact requirements.
xsaccess
- package restriction - server does not return artifact, if it already exists in the same package
xsapp
- package hierarchy restriction - server does not return artifact, if it already exists in the package hierarchy
if projectionLocation
is not provided: artifacts will be returned without a check (as long as they appear in the .project file)
[2] groupName
: stored at both the project level [a] (optionally) and artifact level [b] (mandatory); the server returns the project's level attribute if there is content, otherwise the server returns the artifact's level attribute
[3] true if artifact already exists. The main purpuse is to support the use of xsaccess
(application access) and xsapp
(application descriptor).
[4] templateContent
: empty if: isTemplateContentRequired = false
getArtifactTemplate
Provides a template description for a specific template in a specific project..
Example Request
var strServiceName = "getArtifactTemplate";
var strSapBackPack = "{\"artifact\":[{\"type\":\"hdbtable\",\"subType\":\"columnstore\"}],\"isTemplateContentRequired\":true}";
var request = new $.net.http.Request($.net.http.GET, strExecPathTemplate);;
request.headers.set('Service-Name', strServiceName);
request.headers.set('SapBackPack', strSapBackPack);
var response = client.request(request, destination).getResponse();
Input and Output
Input
Name | mandatory | Description |
---|---|---|
List | Y | Artifacts list |
type [a] | Y | Artifact type (file suffix) |
subType [a] | Artifact sub type (for example, Modification Exit for XSOData) | |
isTemplateContentRequired | Y | true: Template content returned |
JSON
{
"artifact": [
{
"type": "xsodata",
"subType": "modificationExit"
}
],
"isTemplateContentRequired": false
}
Output
Name | mandatory | Description |
---|---|---|
List | Y | Project's artifacts list with related content |
type [a] | Y | Artifact type (file suffix) |
subType [a] | Artifact sub type (for example, Modification Exit for XSOData) | |
name [b] | Y | Artifact name (for label) |
groupName [2],[a]or[b] | Y | Artifact group name |
desc [b] | Y | Artifact description (for tooltip) |
version [b] | Y | Artifact version (compatibility indicator for client-side) |
List | Y | Artifact template parameters for template instantiation |
name | Y | Artifact template parameter name |
defaultVal | Artifact template parameter default value | |
desc | Y | Artifact template parameter description (for tooltip) |
templateContent [4],[c] | Artifact template content |
JSON
{
"artifact": [
{
"type": "xsodata",
"subType": "modificationExit",
"name": "OData descriptor",
"groupName": "XS",
"desc": "OData descriptor with Modification Exit",
"version": 1,
"templateParam": [
{
"name": "artifactName",
"defaultVal": "",
"desc": "Artifact name"
}
],
"templateContent": ""
}
]
}
[1] type
, subType
: based on artifact's file name - <artifactType
>-<artifactSubType
>
[2] templateContent
: empty if: isTemplateContentRequired
= false
getInstantiatedArtifact
Provides an instantiated template based on asset of parameters.
Example Request
var strServiceName = "getInstantiatedArtifact";
var strSapBackPack = "{\"artifact\":[{\"type\":\"hdbtable\",\"subType\":\"columnstore\",\"templateParam\":[{\"name\":\"schemaType\",\"val\":\"HUGO\"}]}]}";
var request = new $.net.http.Request($.net.http.GET, strExecPathTemplate);;
request.headers.set('Service-Name', strServiceName);
request.headers.set('SapBackPack', strSapBackPack);
var response = client.request(request, destination).getResponse();
Input and Output
Input
Name | mandatory | Description |
---|---|---|
List | Y | Artifacts list |
type | Y | Artifact type (file suffix) |
subType | Artifact sub type (for example, Modification Exit for XSOData) | |
List | Optional list of template parameters | |
name | Artifact template parameter name | |
val | Artifact template parameter value |
JSON
{
"artifact": [
{
"type": "xsodata",
"subType": "modificationExit",
"templateParam": [
{
"name": "artifactName",
"val": "MyArtifact"
}
]
}
]
}
Output
Name | mandatory | Description |
---|---|---|
List | Y | Artifacts list |
type [a] | Y | Artifact type (file suffix) |
subType [a] | Artifact sub type (for example, Modification Exit for XSOData) | |
isTemplateContentRequired | Y | Instantiated artifact content, based on template and parameters |
JSON
{
"artifact": [
{
"type": "xsodata",
"subType": "modificationExit",
"instantiatedContent": "TemplateContentWithInjectedParamVals"
}
]
}
[1] artifactType
, artifactSubType
: based on artifact's file name <artifactType
>-<artifactSubType
>
Create Application Support
Based on the functionality for copying complete packages including all their content and the available mustache template renderer was introduced funcionality to enable the creation of complete project or application specific content with one REST API call in SP09.
Create Internal Application
Creates an internal Application based on a location in the repository (package) including all elements of the content neccessary for this application.
Example Request
var strServiceName = "CreateApplication";
var oSapBackPack =
{
"source" : "home/hana/xs/dt/base/work/wolfgang/project/template"
,"target" : "home/hana/xs/dt/base/work/wolfgang/project/target/Dest1"
,"parameters" : [{"name":"test","val":"HUGO"}
,{"name":"test2","val":"MORITZ"}
,{"name":"Test4","val":"MAX"}]
}
var sapBackPack = JSON.stringify(oSapBackPack);
geturl = $.ajax({
url: "/sap/hana/xs/dt/base/workspace",
type: 'POST',
headers: {
"Orion-Version": "1",
'Service-Name': strServiceName,
"Content-Type": "application/json",
"SapBackPack" : sapBackPack,
"X-CSRF-Token": frames.securityToken
},
Input and Output
Input
Name | mandatory | Description |
---|---|---|
source | Y | repository location of the template package |
target | Y | repository location of the generated package/application |
parameters | Y | JSON string containing the set of variable name a and value combinations neccessary for mustache rendcering. |
JSON
{
"source" : "home/hana/xs/dt/base/work/wolfgang/project/template"
,"target" : "home/hana/xs/dt/base/work/wolfgang/project/target/Dest1"
,"parameters" : [{"name":"test","val":"HUGO"}
,{"name":"test2","val":"MORITZ"}
,{"name":"Test4","val":"MAX"}]
}
Output
http return code cotaining or success information or error code. API specific error code is 555
Create External Application
This functionality enables the creation of Appications from zipped content. The zipped content can be provided in the body of the http request or at a location in the repository.
The other steps are executed in the same way like in the create application functionality- mustache rendering is executed and content is creatred at the specified location.
Example Request
var strServiceName = "CreateApplication";
var oSapBackPack =
{
"source" : ""
,"target" : "home/hana/xs/dt/base/work/wolfgang/project/target"
,"sourceType" : "remote"
,"parameters" : [
{"name":"Bla","val":"HUGO"}
,{"name":"Blu","val":"MORITZ"}
,{"name":"Bli","val":"GrueTZe"}
,{"name":"Ble","val":"Max"}
]
}
var sapBackPack = JSON.stringify(oSapBackPack);
geturl = $.ajax({
url: "/sap/hana/xs/dt/base/workspace",
type: 'POST',
processData: false,
contentType: type,
data: contents,
headers: {
"Orion-Version": "1",
'Service-Name': strServiceName,
"Content-Type": type,
"SapBackPack" : sapBackPack,
"X-CSRF-Token": frames.securityToken,
"X-Create-Options": "no-overwrite"
},
success: onComplete,
error: onError
});
Input and Output
Input
Name | mandatory | Description |
---|---|---|
source | Y | repository location of the zipped content. Empty if sourceType equals internal |
target | Y | repository location of the generated package/application |
sourceType | Y | specifies if the zipped content is provide in the data section of the request or in the location specified in the source parameter |
parameters | Y | JSON string containing the set of variable name a and value combinations neccessary for mustache rendcering. |
data | Y | contains the zipped object if sourceType value equals external |
JSON
{
"source" : ""
,"target" : "home/hana/xs/dt/base/work/wolfgang/project/target"
,"sourceType" : "remote"
,"parameters" : [
{"name":"Bla","val":"HUGO"}
,{"name":"Blu","val":"MORITZ"}
,{"name":"Bli","val":"GrueTZe"}
,{"name":"Ble","val":"Max"}
]
}
Output
Copntains or OK Code for execution or error information returned in API specific RC 555.