Explore the API with qqurl

IN THIS ARTICLE 

Outlines how to use the qqurl command-line utility to explore the REST API of Qumulo Core

REQUIREMENTS

• Cluster running Qumulo Core 2.14.4 or below
• Command line (CLI) tools installed via API & Tools tab

Reference the article QQ CLI: Install Command-Line Tools for additional details. If you are Qumulo Core 2.14.5 or above, refer to Explore the API with qq raw.

DETAILS

Explore the REST API of Qumulo Core, and learn about its URLs, using a command-line utility with easy login.

This approach is most useful if you are trying to learn about the URL structure and responses of the Qumulo Core REST API in preparation of writing your own scripts against the API.

• If you are writing scripts in Python, it may be easier to use the Python bindings included in the Qumulo Core CLI tools.
• If you are not writing scripts but want to administer Qumulo Core from the command line, you probably want to use the qq CLI.

A REST-style API is organized as a set of URLs, each of which responds to one or more HTTP verbs such as GET, PUT, POST, PATCH and DELETE. The qqurl utility, included with the Qumulo Core CLI tools, allows you to make requests using those verbs to Qumulo URLs and simplifies the authentication that would otherwise be required to issue requests using tools such as "curl." As a convenience, it also allows using URL references that are relative to the local cluster without always specifying a full URL, include a host name, the http: prefix, and so on.

Let’s discover some URLs in the Qumulo Core REST API URL space.

To start, log into a Qumulo node using ssh. Try the following command:

qqurl GET /v1/version
{
"build_date": "2018-05-29T21:54:17Z", 
"build_id": "112173.1.14", 
"flavor": "release", 
"revision_id": "Qumulo Core 2.8.5"
}

Note that we’ve given qqurl an HTTP verb, GET, and a URL that is relative to the local node. There is no need to supply the prefix, http://qumulo-1, which you would need using other tools.

NOTE: Relative URLs like the one above can be found in the Interactive API Overview page in the UI by clicking API & Tools.

The /v1/version API did not require authentication. Let’s try a URL that does.

qqurl GET /v1/files/quotas/

qumulo.lib.request.RequestError: 
Error 401: unknown: Need to log in first to establish credentials.

To log in, we can use the login feature of qqurl:

qqurl -u admin -p

qqurl GET /v1/files/quotas/
{
"paging": {
"next": "/v1/files/quotas/?after=14103884135&limit=16", 
"prev": ""
}, 
"quotas": [
{
"id": "2", 
"limit": "52000000000000"
}, 
{
"id": "1000003", 
"limit": "30000000000000"},
]
}

Note that the latter request succeeded because of a previous qqurl command including a name and password that had already stored the credentials in a local credential cache. That cache is shared between the qq and qqurl commands. Once you’ve logged in using one, you can move freely between them.

We can also use HTTP verbs other than GET. When using POST, PUT, or PATCH, the command will wait for input, shown by the bold text, that will be included in the request body. We can create a snapshot as follows:

qqurl POST /v1/snapshots/
{ "name": "bananagrams", "expiration": "2018-06-01T00:00:00Z" }
{
 "created_by_policy": false, 
 "directory_name": "1814932_bananagrams", 
 "expiration": "2018-06-01T00:00:00Z", 
 "id": 1814932, 
 "name": "bananagrams", 
 "source_path": "/", 
 "timestamp": "2018-05-31T18:27:07.279498115Z"
}

To use qqurl effectively, you need to know what URLs to try and what request bodies they expect. Look at the API & Tools page in the UI for items that look like this: 

The last line item, /v1/snapshots/:id:, shows the shape of a URL that you can use. The entry on the API & Tools Page will also display elements that are required (or optional) in the JSON request body, if any.

RESOLUTION 

You should now be able to experiment with Qumulo Core's REST API endpoints and discover their behavior directly. Use this skill in preparation for your own scripting or write scripts that directly construct URLs to call qqurl.

ADDITIONAL RESOURCES

QQ CLI: Install Command-Line Tools

QQ CLI: Get Started

Explore the API with qq raw

Like what you see? Share this article with your network!