Skip to Content

Introduction

SAP Landscape Management (LaMa) has REST Application Programming Interface that can be used to further automate your operations. You can call the APIs from other applications or your own scripts. This is a basic how-to on testing LaMa REST APIs to help you understand what you can do with this feature. After going through the steps below, hopefully you will be in a better position to do some interesting integration via REST API calls to your LaMa instance.

We will first do some tests with a popular REST client known as “Postman”. Next, we will repeat the tests using Curl from the command prompt. Through these 2 methods you will then feel more comfortable to write your REST API calls from your choice of platform such as shell scripts, Python, Java, Javascript, C etc.

Prerequisite

You should have a non-production LaMa available when first starting to play with these APIs. You can easily mess things up if you do it in production. My tests were done in a LaMa trial appliance provisioned using SAP Cloud Appliance Library (CAL) to a public cloud. For more info on CAL go to https://cal.sap.com/. This blog gives a concise overview of the trial appliance in case you have not heard of it before.

Test with Postman

  1. Download and install Postman from https://www.getpostman.com/apps (please register for free – Installation steps are self-explanatory so are not covered here). Note: I used version 6.5.2 for Windows 64.
  2. Note down the IP address of LaMa.
  3. Make sure you can access the following link from your browser:
    http://<IP address of LaMa>:50000/lama-api
  4. Perform a basic GET operation in browser to ensure it works.
    http://<IP address of LaMa>:50000/lama-api/instances
  5. Repeat above basic GET operation in Postman
    • 5a. Launch Postman
    • 5b. Click on New
    • 5c. Select “Get Request …” and give it a name and description and then save it
    • 5d. Fill in the URL for GET instances previously tested in the browser
    • 5e. Select tab “Authorization” and choose Type of “Basic Auth” and fill in the Username and Password of LaMa
    • 5f. Click on “Send”
    • 5g. You should now see a response from LaMa such as below:
  6. Now let’s get ready to perform a PATCH operation which is an update operation. Other operations that perform updates are POST, PUT and DELETE.
    • 6a. First note down the instance ID from the previous GET operation
    • 6b. In our example this is from line 7: DatabaseName.ATD.DatabaseType.HDB.DatabaseHost.saphdbatd.example.com
    • 6c. For any operation that makes a change we need to use Cross-Site-Request-Forgery token “x-csrf-token”. This first needs to be obtained from LaMa using a Fetch as described below. The token expires after a few minutes (30 mins is the default), so you may need to fetch it again. After it is fetched it needs to be used in any update operation.
  7. Fetch x-csrf-token
    • 7a. Create a new basic GET request
    • 7b. Click on New
    • 7c. Select “Get Request …” and give it a name and description and then save it
    • 7d. Fill in the following URL replacing the IP address with your LaMa IP address. Note the API call is “xsrftoken”
    • 7e. Select tab Authorization and choose Type of “Basic Auth” and fill in the Username and Password of LaMa
    • 7f. We also need to fill in the header information. By default, the call will not return anything unless we have the key “X-CSRF-Token” and value of “Fetch” in the header
    • 7g. Click on “Headers” tab and fill in as below:
    • 7h. Click on Send 
    • 7i. Click on “Headers” tab in the output section. You will now get an output as below:
    • 7j. Copy the token into the Clipboard. We will use this for every API call that performs an update such as POST, PATCH, PUT, DELETE (if it is not expired)
  8. Perform a PATCH operation
    • 8a. We will perform a PATCH operation on the instance ID we noted previously
    • 8b. Click on New
    • 8c. Select “Get Request …” and give it a name and description and then save it                                                                                    
    • 8d. Change the GET to a PATCH in Postman     
    • 8e. Fill in the URL using the instance ID – http://<LaMa IP>:50000/lama-api/instances/DatabaseName.ATD.DatabaseType.HDB.DatabaseHost.saphdbatd.example.com                                                  
    • 8f. Select tab “Authorization” and choose Type of “Basic Auth” and fill in the Username and Password of LaMa                                                                   
    • 8g. Click on “Preview Request” – you should get the message below.                                                                                           
    • 8h. Click on “Body” tab                                                                       
    • 8i. Click on radio button “raw”:                                                          
    • 8j. Change “Text” to “JSON”                                                              
    • 8k. Enter the following JSON data that we will send to LaMa as part of the PATCH method call                                                     
    • 8l. Click on “Headers” tab                                                                  
    • 8m. Enter the X-CSRF-Token info:                                                      
    • 8n. Click on Send
    • 8o. You should see a response as below with status of OK (200):    
    • 8p. If you get an error or status shows something like “Forbidden” you may need to fetch the token again as it may have expired in the meantime.
    • 8q. Check the change in your LaMa instance (see below)                                                                       

 

Test with Curl

Postman also gives you code that you can execute outside of the application such as Curl, Python, Java etc.  However, please note that you will need to specify authentication method as this is not included in the code snippet.

1. After executing an operation in Postman, you can click on “code”

We will use a command line utility called “Curl” to perform the same procedure we did with Postman. Curl stands for Client URL and can be used to perform basic interaction with web servers.

Note that the x-csrf-token value needs to be used in the same session. This is part of the security mechanism to ensure the key cannot be used in another session. Postman handles it for us but with Curl you need to use cookies to tell it is the same session.

If you are on a Mac, then the command “curl” should already exist. If on Windows 10 then you should also have Curl. Just try running “curl –version” from the command prompt. If you have an older Windows version, then you can get the Curl utility from http://www.curl.com/download/.

Other options are to use Cygwin shell which includes the curl command but an overkill for what we are doing unless you already have it installed.

2. First let’s get the X-CSRF-Token.

We will collect cookie information in the file cookiejar.dat which we will use in the subsequent call to perform an update.

3. Run the command

curl --user Administrator --header "X-CSRF-Token: Fetch" --cookie-jar cookiejar.dat --verbose http://<LaMa IP address>:50000/lama-api/xsrftoken

 

4. Since we used the “–verbose” flag we will see the token value displayed in the output. Copy the token value to your clipboard for use in the next step.

“< x-csrf-token: ZTOsMK5wwj_3Mp6IpR5oqYOgV869lDgYRgA”

 

5. Assign the token value to a variable for ease.

 

6. If Mac or Cygwin

export CSRFTOKEN=ZTOsMK5wwj_3Mp6IpR5oqYOgV869lDgYRgA

7. If Windows command prompt

set CSRFTOKEN=ZTOsMK5wwj_3Mp6IpR5oqYOgV869lDgYRgA

8. Add the data we need to send to LaMa into file “data.json”

{
          "instanceRequirements": {
                "requiredSAPS": 100,
                "requiredMemory": 256
          }
}

 

9. Now we are ready to make the PATCH call to LaMa using the files cookiejar.dat (so that the token is accepted) and data.json (the data that we are sending).

 

10. Mac or Cygwin

curl --user Administrator --header "Content-Type: application/json" --header "X-CSRF-Token: $CSRFTOKEN" --cookie cookiejar.dat --verbose --data @data.json -X PATCH http://<LaMa IP Address>:50000/lama-api/instances/DatabaseName.ATD.DatabaseType.HDB.DatabaseHost.saphdbatd.example.com

 

11. Windows command prompt:

curl --user Administrator --header "Content-Type: application/json" --header "X-CSRF-Token: %CSRFTOKEN%" --cookie cookiejar.dat --verbose --data @data.json -X PATCH http://<LaMa IP Address>:50000/lama-api/instances/DatabaseName.ATD.DatabaseType.HDB.DatabaseHost.saphdbatd.example.com

 

12. If you do not want to be prompted for password, you can specify it as “–user Administrator:<password>”

13. You should get a response that UPDATE was performed like what you got in Postman but less nicely formatted.

{"responses":[{"entity":{"entityType":"INSTANCE","entityId":"DatabaseName.ATD.DatabaseType.HDB.DatabaseHost.saphdbatd.example.com","links":[{"href":"http://35.230.112.24:50000/lama-api/instances/DatabaseName.ATD.DatabaseType.HDB.DatabaseHost.saphdbatd.example.com","rel":"self","method":"GET"}]},"operation":"UPDATE","status":200}]}

 

Conclusion:

The above covered the basics of using the REST APIs and you should now feel comfortable tackling more advanced procedures with these APIs.  For further information please refer to the following documentation:

To report this post you need to login first.

1 Comment

You must be Logged on to comment or reply to a post.

Leave a Reply