Red Hat Training

A Red Hat training course is available for Red Hat Gluster Storage

Appendix B. API Usage with cURL

This appendix provides instructions on adapting REST requests for use with cURL. cURL is a command line tool for transferring data across various protocols, including HTTP, and supports multiple platforms such as Linux, Windows, Mac OS and Solaris. Most Linux distributions include cURL as a package.
Installing cURL

A Red Hat Enterprise Linux user installs cURL with the following terminal command:

yum install curl
For other platforms, seek installation instructions on the cURL website (http://curl.haxx.se/).
Using cURL

cURL uses a command line interface to send requests to a HTTP server. Integrating a request requires the following command syntax: 

Usage: curl [options]uri
The uri refers to target HTTP address to send the request. This is a location on your Red Hat Storage Console host within the API entry point path (/api).

cURL options

-X COMMAND, --request COMMAND
The request command to use. In the context of the REST API, use GET, POST, PUT or DELETE.
Example: -X GET
-H LINE, --header LINE
HTTP header to include with the request. Use multiple header options if more than one header is required.
Example: -H "Accept: application/xml" -H "Content-Type: application/xml"
-u USERNAME:PASSWORD, --user USERNAME:PASSWORD
The username and password of the Red Hat Storage Console user. This attribute acts as a convenient replacement for the Authorization: header.
Example: -u admin@internal:p@55w0rd!
--cacert CERTIFICATE
The location of the certificate file for SSL communication to the REST API. The certificate file is saved locally on the client machine. Use the -k attribute to bypass SSL. See Chapter 2, Authentication and Security for more information on obtaining a certificate.
Example: --cacert ~/Certificates/rhsc.cer
-d BODY, --data BODY
The body to send for requests. Use with POST, PUT and DELETE requests. Ensure to specify the Content-Type: application/xml header if a body exists in the request.
Example: -d "<bricks><brick><server_id>fcb46b88-f32e-11e1-918a-0050568c4349</server_id><brick_dir>/export/data/brick3</brick_dir></brick></bricks>"
Examples

The following examples show how to adapt REST requests to cURL command syntax:

Example B.1. GET request

The following GET request lists the clusters in the cluster collection. Note that a GET request does not contain a body. 
GET /api/clusters HTTP/1.1
Accept: application/xml
Adapt the method (GET), header (Accept: application/xml) and URI (https://[RHSC Host]/api/clusters) into the following cURL command: 
$ curl -X GET -H "Accept: application/xml" -u [USER:PASS] --cacert [CERT] https://[RHSC Host]/api/clusters
An XML representation of the clusters collection displays.

Example B.2. POST request

The following POST request creates a volume in the server collection. Note that a POST request requires a body. 
POST api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes HTTP/1.1
Accept: application/xml
Content-type: application/xml

<gluster_volume>
  <name>data</name>
  <volume_type>DISTRIBUTE</volume_type>
  <bricks>
    <brick>
      <server_id>fcb46b88-f32e-11e1-918a-0050568c4349</server_id>
      <brick_dir>/export/data/brick1</brick_dir>
    </brick>
    <brick>
      <server_id>de173e6a-fb05-11e1-a2fc-0050568c4349</server_id>
      <brick_dir>/export/data/brick2</brick_dir>
    </brick>
  </bricks>
</gluster_volume>
Adapt the method (POST), headers (Accept: application/xml and Content-type: application/xml), URI (https://[RHSC Host]/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes) and request body into the following cURL command: 
curl -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" -u [USER:PASS] --cacert [CERT] https://[RHSC HOST]/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95/glustervolumes -d "<gluster_volume><name>data</name><volume_type>DISTRIBUTE</volume_type><bricks><brick><server_id>fcb46b88-f32e-11e1-918a-0050568c4349</server_id><brick_dir>/export/data/brick1</brick_dir></brick><brick><server_id>de173e6a-fb05-11e1-a2fc-0050568c4349</server_id><brick_dir>/export/data/brick2</brick_dir></brick></bricks></gluster_volume>"
The REST API creates a new volume and displays an XML representation of the resource.

Example B.3. PUT request

The following PUT request updates the cluster. Note that a PUT request requires a body. 
PUT /api/clusters/99408929-82cf-4dc7-a532-9d998063fa95 HTTP/1.1
Accept: application/xml
Content-type: application/xml

<cluster>
    <description>Cluster 1</description>
</cluster>
Adapt the method (PUT), headers (Accept: application/xml and Content-type: application/xml), URI (https://[RHSC Host]/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95) and request body into the following cURL command: 
$ curl -X PUT -H "Accept: application/xml" -H "Content-type: application/xml" -u [USER:PASS] --cacert [CERT] -d "<cluster><description>Cluster 1</description></cluster>" https://[RHSC Host]/api/clusters/99408929-82cf-4dc7-a532-9d998063fa95
The REST API updates the cluster with a new description.

Example B.4. DELETE request

The following DELETE request removes a cluster resource. 
DELETE /api/clusters/082c794b-771f-452f-83c9-b2b5a19c0399 HTTP/1.1
Adapt the method (DELETE) and URI (https://[RHSC Host]/api/clusters/082c794b-771f-452f-83c9-b2b5a19c0399) into the following cURL command: 
$ curl -X DELETE -u [USER:PASS] --cacert [CERT] https://[RHSC Host]/api/clusters/082c794b-771f-452f-83c9-b2b5a19c0399
The REST API removes the cluster. Note the Accept: application/xml request header is optional due to the empty result of DELETE requests.
cURL Library (libcurl)

In addition the the standard command line tools, cURL also features libcurl, a library for programming language integration. For more information on supported programming languages and integration methods, see the libcurl website (http://curl.haxx.se/libcurl/).

22632%2C+Console+Developer+Guide-322-09-2014+17%3A11%3A35Report a bug