Skip to content

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"
        ]

    }
}

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

Last update: August 12, 2020