Upon receiving an HTTP request sent through the OneFS API, the cluster’s web server (Apache) verifies the username and password credentials – either through HTTP Basic Authentication for single requests or via an established session to a single node for multiple requests.
Once the user has been successfully authenticated, OneFS role-based access control (RBAC) then verifies the privileges associated with the account and, if sufficient, enables access to either the /ifs file system, or to the cluster configuration, as specified in the request URL.
The request URL that calls the API is comprised of a base URL and end-point:
And the response is usually along the lines of the following:
Or from the CLI using the ‘curl’ utility:
# curl -X GET https://10.224.127.8:8080/platform/21/audit/settings/global --insecure --basic --user <username:password>
{
"settings" :
{
"audited_zones" : [],
"auto_purging_enabled" : false,
"cee_server_uris" : [],
"config_auditing_enabled" : false,
"config_syslog_certificate_id" : "",
"config_syslog_enabled" : false,
"config_syslog_servers" : [],
"config_syslog_tls_enabled" : false,
"hostname" : "",
"protocol_auditing_enabled" : false,
"protocol_syslog_certificate_id" : "",
"protocol_syslog_servers" : [],
"protocol_syslog_tls_enabled" : false,
"retention_period" : 180,
"system_auditing_enabled" : false,
"system_syslog_certificate_id" : "",
"system_syslog_enabled" : false,
"system_syslog_servers" : [],
"system_syslog_tls_enabled" : false
}
}
From the CLI, the ‘curl’ output can be parsed using standard shell commands and utilities. For example, to find the cluster’s OneFS version:
# curl -X GET https://10.224.127.8:8080/platform/21/cluster/config --insecure --basic --user root:a | grep -I release "release" : "9.8.0.0",
In the event that authentication fails for some reason, a response similar to the following notification will be returned:
When it comes to finding the appropriate platform API endpoint, the following ‘describe’ suffix can be used at the base level (platform) within the URL to list all the available options:
https://<cluster_IP>:8080/platform?describe
For example:
As can be seen above, the endpoints are appropriately named to aid navigation of the API.
When used on an endpoint, rather than a path, the ‘describe’ option returns a collection of JSON of methods and fields. In addition to the supported methods (GET, POST, DELETE), the output also includes all support fields and types. Given the breadth of information, it is best viewed from a web browser using a JSON viewer add-on/extension, such as the popular ‘JSONview’ utility. For example:
In addition to the ‘describe’ syntax, the platform API also recognizes the ‘list’ suffix. This can be used at any point in the API hierarchy, in conjunction with ‘describe’, to report the available endpoint(s) for a particular OneFS feature or function. For example, to show the pAPI options for the S3 protocol:
https://<cluster_IP>:8080/platform/21/protocols/S3?describe&list
For example, we can see that OneFS currently provides seven API endpoints for the S3 protocol:
Note that the numerical ‘protocol version’ must be included in the URL – in this case version 21 (the most current).
Typically, new features and API primitives are added to new releases by incrementing the pAPI version number. As such, the endpoints functionality is consistent in each version. For example, the /1/cluster/config endpoint is not be changed to add new functionality, and any new calls and features are uprev’d and placed into the next version. That said, the version number is not guaranteed to be whole number. For example, an incremental version number (v5.1) was introduced back in OneFS 8.1.0.4 to accommodate the NDU rolling reboot endpoint. Querying a particular version will only report the API endpoints that were available at that point in time. For instance, since the S3 protocol was only added in pAPI v10, querying earlier versions will not return any of the seven current endpoints:
Additionally, if you already know the CLI command for something you can get the REST endpoint etc. by simply running:
# isi --debug <command>
The output from the debug flag contains the HTTP REST traffic in both directions, including both endpoint and payloads. For example, take the following ‘isi dedupe settings view’ CLI command output, both with and without the –debug flag:
# isi dedupe settings view Dedupe Schedule: - Paths: /ifs/data Assess Paths: -
And:
# isi --debug dedupe settings view
2024-07-21 21:59:52,488 DEBUG rest.py:80: >>>GET ['1', 'dedupe', 'settings']
2024-07-21 21:59:52,488 DEBUG rest.py:81: args={}
body={}
2024-07-21 21:59:52,503 DEBUG rest.py:106: <<<(200, {'content-type': 'application/json', 'allow': 'GET, PUT, HEAD', 'status': '200 Ok'}, b'\n{\n"settings" : \n{\n"assess_paths" : [],\n"dedupe_schedule" : null,\n"paths" : [ "/ifs/data" ]\n}\n}\n')
Dedupe Schedule: -
Paths: /ifs/data
Assess Paths: -
The first line of output above shows that the equivalent endpoint for this CLI command is:
/1/dedupe/settings/
From this, the API URL can be inferred:
# curl -X GET https://10.1.10.20:8080/platform/1/dedupe/settings/ --insecure --basic --user <username>:<password>
{
"settings" :
{
"assess_paths" : [],
"dedupe_schedule" : null,
"paths" : [ "/ifs/data" ]
}
}
In addition to ‘curl’, OneFS also offers an ‘isi_papi_tool’ CLI utility for querying a node’s platform API endpoints. For example, the following syntax can be used to view the status of a node’s SMB sessions via the ’16/protocols/smb/sessions’ endpoint:
# isi_papi_tool GET 16/protocols/smb/sessions | egrep "computer|client_type|encryption"
Or to see all the SMB sessions across the entire cluster with ‘isi_papi_tool’:
# for node in $(isi_nodes %{lnn}); do echo Sessions on Node $node:; isi_papi_tool GET 16/protocols/smb/sessions\?lnn=$node | egrep "computer|client_type|encryption";done
Sessions on Node 1:
Sessions on Node 2:
"client_type" : "SMB 3.1.1",
"computer" : "10.1.10.22",
"encryption" : false,
Sessions on Node 3:
Sessions on Node 4:
Sessions on Node 5:
"client_type" : "SMB 3.1.1",
"computer" : "10.1.10.25",
"encryption" : true,
Sessions on Node 9:
In the next article in this series, we’ll turn our attention to OneFS RAN, the RESTful namespace access API.