IN THIS ARTICLE
Outlines how to use the qqurl command-line utility to explore the REST API of Qumulo Core
- Cluster running Qumulo Core
- Command line (CLI) tools installed via API & Tools tab
Reference the article QQ CLI: Install Command-Line Tools for additional 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
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/
To log in, we can use the login feature of qqurl:
qqurl -u admin -p
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/
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.
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.
Like what you see? Share this article with your network!