Print Email PDF

Explore the API with qqurl

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: 

Screen_Shot_2018-06-01_at_12.05.33_PM.png

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.

Was this article helpful?
1 out of 1 found this helpful

Comments

0 comments

Please sign in to leave a comment.

Have more questions?
Open a Case
Share it, if you like it.