Using curl as the data transfer tool
To send requests to the REST interface on an appliance, you can use curl as the data transfer tool.
A request sent with curl usually has three main parts: the curl command, one or multiple options, and a URL.
For example, in the following backup request, the curl command appears with the -b option for sending cookies that have been collected in a text file and the -o option, which stores the output of the request in another file. The -X option is for the request method.
curl -b cookies.txt -X POST "$REST/backup" -o filename.backup
The URL is specified as a variable that has the IP address, port number, and other information needed for access to the REST interface on an appliance as its value. It is followed by the name of the activity that is to be performed.
Using these and other options of curl together with the appropriate URLs, you can send requests to the REST interface on an appliance to perform activities as needed.
The curl data transfer tool is available under Linux and other UNIX operating systems and described in full detail, for example, on the curl man page.
Request methods
The request method is specified in curl by the -X option. When working with the REST interface on an appliance, the GET, POST, PUT, and DELETE methods can be used, for example, as follows:
curl -X POST <URL>
If no request method is specified, GET is the default method.
Headers
When a header is sent with a request, it is specified by the -H option, for example, as follows:
curl -H " <header name>:<header value>" -X POST <URL>
You can send multiple headers within one request, repeating the -H option letter before each header.
curl -H "<header name 1>:<header value 1>" -H "<header name 2>:<header value 2>" -X POST <URL>
A request normally includes an Accept header that has application/atom+xml as its value. In curl, Accept:
*/* is sent as a default, which is accepted by the REST interface, so you can leave out this header in many cases.
However, if you send data in the body of a request, you must include the Content-Type header with application/atom+xml as its value. You must also include the Content-Length header and set it correctly. The latter is done in curl by default, so you need not do it explicitly when using this tool.
If you want to include the header of the response that you receive upon a request in its output, you must insert the -i option.
curl -i -c cookies.txt -H "Authorization: Basic YWRtaW46d2ViZ2F0ZXdheQ==" -X POST "$REST/login"
The -v option creates verbose output, which means that the request header is included.
URLs
A URL in a request specifies a protocol, which can be HTTP or HTTPS in communication with the REST interface, the IP address or host name and the port number of the appliance that a request is sent to, and the internal path on the appliance to the REST interface.
This is followed by the name of the activity that should be performed and further parameters if there are any.
As the REST interface is located within the configurator subsystem of an appliance, the internal name of this subsystem, which is Konfigurator, appears in the URL.
A URL in, for example, a logon request, could therefore look as follows:
curl -X POST "http://localhost:4711/Konfigurator/$REST /login?userName=myusername&pass=mypassword"
In this request, the URL also has query parameters for the logon credentials. Query parameters are introduced by a ? (question mark) and separated by an & (ampersand), as shown. A URL can also have matrix parameters, which are introduced by a ; (semicolon).
For correct URL encoding, spaces in a URL must be filled with the symbols %20. So, for example, Bob Smith becomes Bob%20Smith.
You can use a variable within a URL for easier code writing and reading. For example, if you have set the $REST
variable accordingly, the above request could look as follows:
curl -X POST "$REST/login?userName=myusername&pass=mypassword"
Sending data in the request body
For sending data in the body of a request, the -d option is used, followed by the name of the file that contains the data.
curl -b cookies.txt -X POST -d @file.txt "$REST/list?name=newlist&type=string"
If you are sending only binary data, the option to use is - - data-binary.
curl -b cookies.txt --data-binary @file.backup -X POST "$REST/restore" -H "Content-Type: text/plain; charset=UTF-8"
You can use the @ symbol after the option name to indicate a file name.