API Specification¶
This document describes the API structure as well as common parameters and expected output.
General¶
Authentication¶
The API uses sessions to control access to the SAP GUI for HTML back-end services, e.g. a session must be established prior to an API method being called.
The identity of the caller will be propagated to the back-end system (principal propagation). Upon successful authentication and authorization by the back-end system, a session is being created. The caller has to use the provided session identification for all subsequent calls to the API.
Standard Return Values¶
| Field | Type (Length) | Required | Description |
|---|---|---|---|
| State | State | Yes | The Status element contains the basic processing results: an error code and message. The message is this element's content, the status code is represented by the 'code' attribute. |
Generic Methods¶
Login¶
Verifies caller credentials and creates a session.
The method does not require any parameters - principal propagation is used to identify the caller.
<Action Name="Login">
<ReturnType Type="Self.Response" Nullable="false"/>
</Action>
POST /Login http/1.1
HTTP/1.1 200 OK
{
"State": {
"ErrorCode": 0,
"SubsequentActions": [],
"PrecedingActions": []
}
}
Logout¶
Terminates session.
<Action Name="Logout">
<ReturnType Type="Self.Response" Nullable="false"/>
</Action>
POST /Logout http/1.1
HTTP/1.1 200 OK
{
"State": {
"ErrorCode": 0,
"SubsequentActions": [],
"PrecedingActions": []
}
}
Home¶
Brings the caller at the beginning of the SAP Transaction (executes a \n command).
<Action Name="Home">
<ReturnType Type="Self.Response" Nullable="false"/>
</Action>
POST /Home http/1.1
HTTP/1.1 200 OK
{
"State": {
"ErrorCode": 0,
"SubsequentActions": [],
"PrecedingActions": []
}
}
Recorded/generated Methods¶
All recorded/generated methods follow the same structure. They contain all the input parameters collected during recording.
| Field | Type | Description |
|---|---|---|
| State | State | Status of the call |
| Output | OUTPUT | Complex type containing all the output parameters collected during recording |
<Action Name="Find">
<Parameter Name="FirstName" Type="Edm.String" Nullable="false"/>
<Parameter Name="LastName" Type="Edm.String" Nullable="false"/>
<ReturnType Type="Self.RESPONSE_Find" Nullable="false"/>
</Action>
POST /Find http/1.1
{
"FirstName": "John"
}
HTTP/1.1 200 OK
{
"Output": {
"Users": [
{
"FirstName": "John",
"LastName": "Wayne",
"UserName": "john.wayne"
}
]
},
"State": {
"ErrorCode": 0,
"SubsequentActions": [
"Get"
],
"PrecedingActions": [
"Home"
]
}
}
Read-Only Functions¶
All read-only functions follow the same structure. General information about invoking OData Functions can be found here.
Every user input will be exposed as an OData parameter. Those have to be specified inside the URL.
| Field | Type | Description |
|---|---|---|
| State | State | Status of the call |
| Output | OUTPUT | Complex type containing all the output parameters collected during recording |
<Function Name="Find">
<Parameter Name="FirstName" Type="Edm.String" Nullable="false"/>
<Parameter Name="LastName" Type="Edm.String" Nullable="false"/>
<ReturnType Type="Self.RESPONSE_Find" Nullable="false"/>
</Function>
GET /Find(FirstName='John',LastName='Wayne') http/1.1
HTTP/1.1 200 OK
{
"Output": {
"Users": [
{
"FirstName": "John",
"LastName": "Wayne",
"UserName": "john.wayne"
}
]
},
"State": {
"ErrorCode": 0,
"SubsequentActions": [
"Get"
],
"PrecedingActions": [
"Home"
]
}
}
Session Cookie¶
The name of the cookie always consists of the prefix mtbsession_ followed by the application name, e.g. mtbsession_su01test for an application called su01test.
Parameter Description¶
State¶
| Name | Type (Length) | Description |
|---|---|---|
| ErrorCode | Integer | The status code of the process. The status code is an unsigned int being either '0' - which means that the process executed successfully - or denotes another status/error reason. |
| PrecedingActions | Collection(String) | List of methods which could be executed before the current method |
| SubsequentActions | Collection(String) | List of methods which could be executed after the current method |
| StatusBarMessage | String | The current status bar message in the SAP GUI for HTML |
Error Messages¶
In case of errors, a corresponding HTTP status together with information about what caused the error is being returned.
| Name | Type (Length) | Description |
|---|---|---|
| status | String | The message associated with the HTTP error code. |
| errorState | State | Details about the state of the call |
| target | String | Location where error occured. |
| details | String[] | More details about the error, if applicable. |
Sample
{
"error": {
"Status": "INTERNAL_SERVER_ERROR",
"ErrorMessage": "Batch execution (partially) failed",
"ErrorState": {
"ErrorCode": 200,
"SubsequentActions": [],
"PrecedingActions": []
},
"Target": "/mtb-bridge/odata/app/krHeea/GetUserDetails",
"Details": [
{
"message": "Step execution status: [{\"ord\":\"1\",\"code\":\"-1\",\"status\":\"Control not found\"}]"
}
]
}
}
Following error codes could be returned by the API.
| HTTP Status | Internal Code | Message | Description |
|---|---|---|---|
| 404 | - | Application not found | No recording found for the specified URL |
| 404 | - | Sequence does not exist | No sequence (user interaction flow) found |
| 500 | 100 | INVALID_SCREEN_STATE | Action cannot be executed on the current screen in the SAP GUI for HTML. |
| 500 | 200 | BATCH_EXECUTION_FAILED | Batch of commands for the current execution could not be executed. |
| 500 | 300 | INVALID_INPUT | Input parameters related errors. |
| 500 | 400 | RESTGUI_CALL_FAILED | The call to the back-end system failed. |
| 500 | 500 | LOGIN_FAILED | The login to the back-end system failed. |
| 500 | 600 | INVALID_OUTPUT | The output received from the back-end does not match OData definition. |
| 500 | 700 | SESSION_INVALID | Session invalid or expired |
| 500 | 999 | UNKNOWN_ERROR | Unknown internal error |