White paper iRMC RESTful Server Management API

1 White paper irmc S RESTful Server Management API. White paper irmc RESTful Server Management API. This document shows a brief overview of different tools using the irmc RESTful API. Content Prerequisites 2. Introduction 2. The General Structure of the RESTful API 3. RESTful example using Postman 4. RESTful Bash Example using cURL 6. RESTful PowerShell Example using cURL 7. RESTful Python Example 9. Page 1 of 9 White paper irmc RESTful Server Management API. Prerequisites This document assumes familiarity of the reader with RESTful web services, JSON, XML and HTTP in general. To learn more about REST, JSON, and XML see the following links: - - - Also you will need a fujitsu PRIMERGY Server with an irmc S4/S5 with eLCM license.

2 Introduction The RESTful Server Management API is a web service API which is served by the irmc Firmware. This document provides a first look on how to take advantage of this in regards of scripting the configuration and update processing with fujitsu PRIMERGY Servers. A RESTful API is an application programming interface which makes use of HTTP operations (mainly GET, DELETE, PUT, POST and PATCH). These HTTP operations submit or return resources which can be either encoded in JSON or XML, similar to a usual web application which returns HTML, JS and CSS. 1. This API is loosely based on the Redfish standard as provided by the DMTF. In modern scripting languages these interfaces are very easy to consume, as there are plenty of libraries and helper tools that will deal with JSON and XML structures and the transport via HTTP(s).

3 1. Page 2 of 9 White paper irmc RESTful Server Management API. The General Structure of the RESTful API. The basic principle behind this API is the mapping of the HTTP operations to the basic CRUD (create, read, update & delete) operations to the resources which are exposed by their URI ( http://< irmc -ip>/rest/v1/Oem/eLCM/OnlineUpdate - the resource here would be OnlineUpdate'). The mapping looks like follows: HTTP Operation CRUD Operation GET Read the resource PATCH Update, to update a resource partially PUT Update (in this case, the complete resource will be replaced by new data POST Creates a new resource or starts a custom action DELETE Deletes the resource Each of these HTTP operations delivers a HTTP return code which reflects to the client whether the request was successful or failed for some reason.)

4 Additionally you will get a return payload depending on the resource, which is described in the specification of this interface. The return codes consist of a number with 3 decimal digits, of which the first digit determines whether an operation was successful and where a possible error most likely occurred. When a return codes starts with 2, the operation was successful, if a 4 is the leading digit there was a client side error ( a wrong URI was specified) and a leading 5 signalizes an internal error on irmc side. To ensure that only the administrator is able to perform changes on the Server , each HTTP operation must be authenticated via HTTP Basic Authentication.

5 Page 3 of 9 White paper irmc RESTful Server Management API. RESTful example using Postman Prerequisites: Google Chrome Postman Extension In this REST-call we will start an Update Check against a repository we specify via an XML file and will check the results. The following resources on the RESTful interface will be used http://<irmc_ip>/rest/v1/Oem/eLCM/OnlineUpdate - Used to start the Update Check [POST]. http://<irmc_ip>/rest/v1/Oem/eLCM/OnlineUpdate/updateCol lection - Used to read or delete the Update Check Result [GET/DELETE]. http://<irmc_ip>/sessionInformation/{sessionId}/status - Used to track the status of the Update Check [GET]. Startup Postman and click the Basic Authentication Tab in the top left navigation to enter the user credentials for the irmc .

6 After entering the credentials click Refresh Headers', so Postman will add the credentials for each following request. After that you can start by checking if an Update Check already exists, by entering the second URI as provided above, check that the HTTP. Method GET' is selected and click send. If there is no updateCollection' result, postman will notify you with the HTTP return code 404' and you are able to really start the Update Check. The start UpdateCheck action expects a repository configuration, which you should provide in XML with the Request. The XML configuration looks like follows: <Repository>. < Server >. <URL> </URL>. <Catalog>DownloadManager/ </Catalog>.

7 </ Server >. <Proxy>. <URL> </URL>. <Port> </Port>. <User> </User>. <Password> </Password>. </Proxy>. </Repository>. Modify this XML to suit your environment, if a proxy is needed, add the details in the designated tags. Page 4 of 9 White paper irmc RESTful Server Management API. After that, you enter the first provided URI into the URI Field of postman, change the HTTP Method from GET to POST and paste our XML into the form-data field. After that you just press send and if everything is correct, you should get an output like follows: This shows that the Server accepted the command and the XML configuration payload and started the Update Check Task. To monitor the progress of this task, you need the provided ID, which will be used in another RESTful URI, which was shown in the table above.

8 When you enter the new URI (http://<irmc_ip>/sessionInformation/4/status) you get, depending on the progress of the task, the following output: Page 5 of 9 White paper irmc RESTful Server Management API. RESTful Bash Example using cURL. Prerequisites: A Linux shell, preferably bash with cURL installed A valid XML File with the configuration as seen in the previous chapter The example you will see here is an extract of a script, which handles input parameters that will not be discussed further, next to a method to call the curl-commands asynchronous to be able to monitor the progress. function start_update_check() {. URI=http://$ Server $BASE_URI.}

9 START=$(date +% ). curl -u $USER:$PASSWD -H "Accept: application/json" $HTTP_POST -i --data $URI >.. statusCode=$(cat . | head -n 1| cut -d$' ' -f2). if [ $statusCode -eq 200 ] || [ $statusCode -eq 202 ]. then sessionId=$(cat . | grep Id | cut -d: -f2 | sed 's/,$//'). echo SESSION: $sessionId else echo 'Update Collection is already existing, please delete beforehand'. exit 1;. fi stillRunning=1. echo while [ $stillRunning = 1 ]. do URI=http://$ Server /sessionInformation/$s essionId/status delayed_status_request $sessionId # The delayed_status_request method starts the below curl command asynchronously #curl -u $USER:$PASSWD -H "Accept: application/json" $HTTP_GET -i -sS $URI >.

10 END=$(date +% ). status=$(cat . | grep Status | cut -d: -f2 | sed 's/,$//'). progress=$(cat . | grep Progress | cut -d: -f2). activity=$(cat . | grep Activity | cut -d: -f2 | sed 's/,$//'). DIFF=$(echo "$END - $START" | bc). duration=${DIFF:0:5}. if [ "$status" != '"terminated regularly"' ]. then if [ "$status" = '"terminated with error"' ]. then echo -e "\nTerminated with error, please see the log-info, exiting.". exit 1. fi sleep 1. echo -ne "\r\033[K Status: $status Current activity: $activity - Current Activity progress: $progress - Duration: $duration ". else stillRunning=0. echo echo 'Update Check finished sucessfully!'. rm . rm . exit 0.]