REST – Representational State Transfer defines a set of functions in which developers can perform requests and receive responses via HTTP protocol such as GET and POST. REST was created 2000 by Roy Fielding and is literally optimized for the internet. Compared to SOAP, REST needs less bandwidth, which makes it perfect to use through the internet. SOAP is also one of the legacy APIs of SAP Landscape Management.
REST was introduced to SAP Landscape Management with the release 3.0 Support Package (SP) 03. Since then, more and more functions were added with every odd numbered release.
The REST API in SAP Landscape Management is intended to control SAP Landscape Management from the outside or even to run SAP Landscape Management in so called Dark Mode. SAP Landscape Management clearly concentrates on automating SAP systems and operations, but sometimes this is only one part of a bigger picture. REST is used by several other vendors from storage to network up to on-premise virtualization. Even public cloud vendors like Amazon AWS or Microsoft Azure are using REST. It became a standard for a whole industry and is now available in SAP Landscape Management as well.
The first evolution of SAP Landscape Management’s REST API was all about activities - basically, to trigger operations, get the status, and delete old activities. At the beginning, the configuration of hosts and instances was not in focus. This changed with the third evolution provided with SP07. POST, PATCH, and PUT were introduced to SAP Landscape Management. Since then, the REST API in SAP Landscape Management were and will be enhanced in the future.
Where to Find the Documentation of the REST API Within SAP Landscape Management?
The documentation is in-built into SAP Landscape Management and can be reached under http(s)://<LaMa-Host>:<Port>/lama-api. The documentation provides all methods and models of SAP Landscape Management. Furthermore, the documentation holds some examples to show how the source code should look like.
Explanations of the figure:
The SP specific documentation can be opened by adding the SP to the link of the REST API like this:
.Code SnippetCopy codeSwitch to dark mode1http(s)://<LaMa-Host>:<Port>/lama-api/?version=3.0.3|5|7|9.0Models in SAP Landscape Management represent all available parameters you can use for all Methods. The higher the SP level the more parameters can be chosen from.
Every method is listed with a specific example of the source code and you can directly jump to the one of interest.
To use the REST API, you have different options to get it done. For all GET methods you can easily use the browser of your choice. Just add the method you want to receive information about and go. The first entry points of using the GET method are:
- /systems
- /instances
- /hosts
- /activities
- /logs
- /pools
While using GET /systems or /pools you will get all available entities in your SAP Landscape Management. If you need a specific system or pool you can filter the output to receive the needed information. To see all systems that are assigned to a specific pool use the following routine:
12GET /systems + ?pool=<Pool Name>
http(s)://<LaMa-host>:<port>/lama-api/systems?pool=<Pool>
As receiving information is quite easy and can be used within a web browser, to trigger an operation or POST configuration usually requires sending data to SAP Landscape Management. In cases like this you have the choice of several tools. A popular one at SAP is Postman. Postman can be used to create your source code and can directly push it to the REST API to test your code.
Besides Postman you also can use other tools or even command line variants. From cURL over PHP to PowerShell you can choose your "weapon" to use the REST API.
The examples in the REST API documentation of SAP Landscape Management consist of JSON files and can be used in tools like Postman via copy & paste. The data itself must be in JSON format, whether you use cURL, PowerShell, or PHP. The command itself might be different because of a different shell or different script language, but the JSON format still applies for the data send.
Take any example from the REST API documentation and reuse it in tools like Postman or in your JSON file if using shell options like cURL.
Besides the JSON format, you need to add an authorization method and some header information to your REST API call. An example with cURL can look like this:
Curl -u User:password -H "Accept:application/json" -H "Content-Type:application/json" -H "x-csrf-token:anything" -X POST -d @<path to json file> http(s)://lama-host:port/lama-api/activities
The x-csrf-token is not verified anymore but was necessary in the first versions of the REST API. It still needs to be part of the header but will not be verified anymore. The token is only valid for 30 minutes and that might not be enough if you trigger any provisioning process in SAP Landscape Management. After the token becomes invalid, the session is ended and needs to be renewed. As SAP Landscape Management only supports JSON as content, the other mandatory header that you have to use within your request is Content-Type:application/json.
The REST API itself doesn’t have its own or specific authorization methods. It relies on the authorization mechanisms of the underlying SAP NetWeaver JAVA, which are:
Authorization Mechanisms for REST API
| Method | Description |
|---|---|
| User ID and Password | User ID and password is the standard mechanism supported by all SAP NetWeaver systems. However, the verification routines used depend on the underlying technology as follows:
|
| Client certificates (X.509) | Many SAP NetWeaver systems also support the use of the SSL protocol and client certificates for user authentication. Authentication takes places using the underlying protocols and no user intervention is necessary, which also provides for an SSO environment. Users need to receive their client certificates from a Certification Authority (CA) as part of a public-key infrastructure (PKI). The CA you choose to use must be designated as a trusted CA on the web server. |
| Secure Network Communication (SNC) | With SNC, user authentication and single sign-on is supported for connections between the SAP GUI for Windows or SAP GUI for Java and SAP NetWeaver AS for ABAP. In this scenario, the user authentication is performed by an external security product. Supported external security products are certified by the SAP Software Partner Program. SAP also offers SAP Single Sign-On. |
| Security Assertion Markup Language (SAML) | The Security Assertion Markup Language (SAML) version 2.0 is a standard for the communication of assertions about principals, typically users. The assertion can include the means by which a subject was authenticated, attributes associated with the subject, and an authorization decision for a given resource. |
| Kerberos (SPNego) | During logon, Kerberos (or SPNego) authentication requires access to an issuing system (for example, Microsoft Active Directory). As this system is typically located within the corporate network, Kerberos cannot be used for most internet-facing deployment scenarios. To enable SSO with Kerberos from outside your corporate network, you might have to set up a VPN connection. |
| Oauth 2.0 | With OAuth 2.0, users allow web-based client applications to access the resources. The application that is authorized by the resource owner accesses the resources on behalf of the user. Thus, users who do not want to reveal their usernames and passwords for the service provider where the resources are located are able to delegate access to the resources using an OAuth 2.0 access token. The OAuth 2.0 authorization protocol enables a third-party application to obtain limited access to a resource using OAuth 2.0 scopes either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the resource, or by allowing the third-party application to obtain access on its own behalf. |