RESTful API Description
The IBM SmartCloud Enterprise RESTful API follows the RESTful principle. It is based on HTTP request using the GET, POST, PUT, and DELETE methods to take actions on the IBM SmartCloud Enterprise platform. RESTful APIs are web-services and thus are often used in a SOA environment, nevertheless some scripting techniques, using for example cURL, are well adapted to use a RESTful API.
The IBM SmartCloud Enterprise RESTful API can return either XML or JSON response depending on the Accept header attribute value. Also some XUL languages preferably use an XML response; however, languages based on JavaScript prefer a JSON response.
The credentials are sent through HTTP basic authentication over HTTPS.
The IBM SmartCloud Enterprise RESTful API is the first building block of all other IBM SmartCloud Enterprise APIs. The Java API is a wrapper around the RESTful API, meaning each Java API method calls the RESTful API; the CLI API call sthe Java API which calls the RESTful API.
The RESTful APIs use a based endpoint address and all possible calls are based on this address.
Calling RESTful API from your browser
The IBM SmartCloud Enterprise accepts a request only from a browser if the user-agent is set to to a specific value. If you use Mozilla FireFox, you can download the switcher-agent plug-in and configure it. You can find more information in the document, which is available after signing in on the IBM SmartCloud Enterprise site.
The example shows calling from a browser:
Using RESTful API with cURL
cURL is a Linux command (also available through Cygwin) that allows you to send HTTP requests.
Let’s take for example a request to retrieve the list of locations using cURL and request for an XML response.
Request:
Response:
To get a JSON response, we must add the “Accept: application/json”header so the request becomes:
The response becomes:
More information is in the document that is available on IBM SmartCloud Enterprise (after singing in).
Using RESTful API with Java
You can call also the RESTful API through a Java program to take action on the IBM SmartCloud Enterprise instead of using the provided Java API.
The next example uses the Apache Commons HttpClient package to send request over HTTP:
Considerations for automation
The same remark as in my previous blogs about CLI API and JAVA API can be done on the RESTful API. Some RESTful APIs are asynchronous, for example, if you launch an HTTP POST request to create a new instance. The request will return a list of instances directly after the request has been posted on the IBM SmartCloud Enterprise platform and not after the instance has been completely created. You have to take this into account while writing your program and thus monitor the completion of the request before launching the next method, of course if this method needs the resource created by the first one.
Download the RESTful API documentation
To download the RESTful API documentation, first access the IBM SmartCloud Enterprise. If you don’t have access, go on http://www.ibm.com/cloud-computing or contact your local IBM representative. Access the documentation as follows:
- Log in at http://www.ibm.com/cloud/enterprise.
- Select the Support tab and click REST API Reference:
Resources
For more information about the IBM SmartCloud Enterprise and other IBM cloud solutions, visit: http://www.ibm.com/cloud-computing.
