Introduction to the OneFS API

OneFS API overview

The OneFS application programming interface (API) is divided into two functional areas: One area enables cluster configuration, management, and monitoring functionality, and the other area enables operations on files and directories on the cluster. You can send requests to the OneFS API through a Representational State Transfer (REST) interface, which is accessed through resource URIs and standard HTTP methods.

When an API request is sent over HTTPS to a cluster IP address or hostname, that request is authenticated and then authorized through role-based access control (RBAC). After the request is approved, access is provided to either file system configuration libraries or directories and files on the cluster.

OneFS API architecture

When you send an HTTP request through the OneFS API, your request is sent to an Apache server. The Apache server verifies your username and password, either through HTTP Basic Authentication for single requests or through an established session to a single node for multiple requests over a period of time.

After the user account is authenticated, the privileges associated with the user account that generated the request are verified by role-based access control (RBAC). If the user account has the required privileges, the request enables access to files and directories on the cluster or to system configuration libraries, based on the resource URL provided in the request.

The following simplified diagram shows the basic flow of the two types of OneFS API requests:



OneFS API terminology

The following terms are relevant to understanding the OneFS API.

Term
Definition
Access point
Root path of the URL to the file system. You can define an access point for any directory in the file system.
Collection
Group of objects of a similar type. For example, all of the user-defined quotas in the system make up a collection of quotas.
Data object
An object that contains content data, such as a file on the system.
Namespace
The file system structure on the cluster.
Object

Containers or data objects.

This term can refer to system configuration data that is created by users, or to a global setting on the system.

For example, a user-created object can be a file system snapshot, quota, share, export, logical unit, or synchronization policy.

An object can also be global settings on the system, such as default share settings, HTTP server settings, snapshot subsystem settings, and so on.

Resource
An object, collection, or function that you can access by a URI.

OneFS API access

By applying standard HTTP methods to resource URIs, you can modify file system settings or access content on any node in a cluster through the OneFS API. When making multiple changes through the OneFS API, it is recommended that you send all requests to a single node to avoid configuration collisions.

OneFS API resource URIs are composed of the following components.

Component
Definition
my_cluster
The IPv4 or IPv6 address or hostname for the cluster
obj_port
The number of the port. The default setting is 8080
access_point
The name of the access point, such as /ifs
resource_path
The file path to the directory that you want to access
api_version
The version of the OneFS API
collection_pattern
The namespace, collection name, and object ID of the resource that you want to configure

In both types of API requests, you can append query parameters to the end of resource URIs to refine your request. For example, you can revise a GET request to return only a set number of entries. In the following example, a maximum of 1,000 SMB shares are returned:

GET https://192.168.1.100:8080/platform/1/protocols/smb/shares&limit="1000"
File system configuration API requests

For file system configuration API requests, the resource URI is composed of the following components:

https://<my_cluster>:<obj_port>/<api-version>/<collection_pattern>

For example, you can send a GET request to the following URI to retrieve all SMB shares on a cluster, where protocols is the namespace, smb is the collection name, and shares is the object ID:

GET https://192.168.1.100:8080/platform/1/protocols/smb/shares
File system access API requests

For file system access APIs requests, the resource URI is composed of the following components:

https://<my_cluster>:<obj_port>/namespace/<access_point>/<resource_path>

For example, you can send a GET request to the following URI to view files that are stored in the folder at /ifs/users/folder1:

GET https://192.168.0.25:8080/namespace/ifs/users/folder1

Additionally, in file system access API requests, you can indicate a special operation in your request by appending a predefined keyword to the end of the resource URI. These keywords must be placed first in the argument list and must not contain any value. If these keywords are placed in any other position in the argument list, the keywords are ignored. Predefined keywords are acl, metadata, worm, and query. For example:

GET https://192.168.0.25:8080/namespace/ifs/users/folder1?acl

HTTP methods

You can apply certain HTTP methods to resource URIs through the OneFS API to modify file system settings or to access file system content.

The following conditions apply to the HTTP methods available for the OneFS API:
  • The GET method returns an object or collection.

  • The HEAD method returns response header metadata without the response body content.

  • The DELETE method removes an object from a collection.

  • The POST method creates objects.

  • The POST method returns a document indicating the success of the request and the location of the created resource.

  • The PUT method enables partial modification of a resource.

  • The PUT and POST methods do not return full resource entity bodies upon success; these methods return success or failure codes.

OneFS API authentication

You can authenticate to OneFS API resource URIs by establishing a session with a cookie or through HTTP Basic Authentication. You can only authenticate to resources for which you have privileges.

You can establish a session by creating a session cookie through the session resource. HTTP Basic Authentication requires more system processing resources and is slower than authentication with a session cookie. If you want to initiate multiple requests over a period of time, it is recommended that you create a session cookie.

HTTP Basic Authentication

With HTTP Basic Authentication (RFC 2617), you can create a standard Authorization header with a valid username and password and send your request to the server. If your username and password are authenticated by the server, you can access the resource.

The following example shows a sample HTTP Basic Authentication request.

GET https://<cluster-ip-or-host-name>:<port>/<resource_uri> HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHN1c2FtZQ==

Privileges

Privileges permit users to complete tasks on an EMC Isilon cluster.

Privileges are associated with an area of cluster administration such as Job Engine, SMB, or statistics.

Privileges have one of two forms:

Action

Allows a user to perform a specific action on a cluster. For example, the ISI_PRIV_LOGIN_SSH privilege allows a user to log in to a cluster through an SSH client.

Read/Write

Allows a user to view or modify a configuration subsystem such as statistics, snapshots, or quotas. For example, the ISI_PRIV_SNAPSHOT privilege allows an administrator to create and delete snapshots and snapshot schedules. A read/write privilege can grant either read-only or read/write access. Read-only access allows a user to view configuration settings; read/write access allows a user to view and modify configuration settings.

Privileges are granted to the user on login to a cluster through the OneFS API, the web administration interface, SSH, or a console session. A token is generated for the user, which includes a list of all privileges granted to the user. Each URI, web-administration interface page, and command requires a specific privilege to view or modify the information available through any of these interfaces.

In some cases, privileges cannot be granted or there are privilege limitations.

  • Privileges are not granted to users that do not connect to the System Zone during login or to users that connect through the deprecated Telnet service, even if they are members of a role.
  • Privileges do not provide administrative access to configuration paths outside of the OneFS API. For example, the ISI_PRIV_SMB privilege does not grant a user the right to configure SMB shares using the Microsoft Management Console (MMC).
  • Privileges do not provide administrative access to all log files. Most log files require root access.

Session cookies

Establish a session by creating a session cookie through the session resource.

You can create a session cookie by sending credentials to a session service resource, which responds with a Set-Cookie header. The Set-Cookie header contains an authentication token that can then be sent with subsequent requests to provide immediate authentication.

Session resource overview

You can set a session cookie that provides extended authentication to a single node.

Object properties
Property
Type
Description
username
String
Specifies the username for the account requesting access to the cluster.
password
String
Specifies the password for the username requesting access to the cluster.
services
Array
Specifies a list of services to obtain access to.
timeout_absolute
Integer
Retrieves the number of seconds before the session expires in a GET request.
timeout_inactive
Integer
Retrieves the number of seconds of inactivity before the session expires in a GET request.
Create a session

You can authenticate to a OneFS API resource URI by creating a session cookie and a session. When you create a session, you extend your authentication to a node for multiple requests over a period of time.

Session cookies are specific to a single node; all requests must be made to the same node from which the session cookie is obtained.
Procedure
  1. Send a POST request to /session/1/session by specifying the JSON content-type in the request header and by specifying your username, password, and the service that you want to access in the request body. In the services property, specify platform for system configuration or namespace for file system access.
    Content-type: application/json
    Body:
    {
    "username": "<string>",
    "password": "<string>",
    "services": ["platform" | “namespace”]
    }
    If the server validates your username and password, a Set-Cookie header is returned.
  2. Obtain the isisessid value from the Set-Cookie header.
    201 Created
    Content-Length:104
    Content-Type:application/json
    Date:Fri, 22 Feb 2013 19:08:36 GMT
    Set-Cookie:isisessid=12345678-abcd-1234-abcd-1234567890ab; path=/;
    HttpOnly; Secure
    Response Body:
    {
    "services":[
    "platform",
    "namespace"
    ],
    "timeout_absolute":14400,
    "timeout_inactive":900,
    "username":"user123"
    }
    This value will authenticate the session when you send a request through a session cookie.
Results
A session is created on the node on which the POST request was executed.
Send a request for access through a session cookie

Authenticate to a session through a session cookie.

Before you begin

Create a session and obtain an isisessid value from the Set-Cookie header.

You do not need to specify a WWW-AUTHENTICATE header.
  • Send a GET request to any API resource by typing the isisessid value in the Cookie request header.
    If the server validates your username and password, access is granted.
Results
Authentication is granted for future requests on the specified node.
Example 

Request example

GET 10.10.111.120:8080/platform/1/quotas
Cookie: isisessid=12345678-abcd-1234-abcd-1234567890ab

Response example

200 OK
Content-Type:application/json
{
//JSON content
}
Get information about the current session

You can send a GET request to obtain information about the current session. If the server validates your session cookie, the system returns a JSON document that contains information about the session. If the server does not validate the session ID contained in the cookie, the server returns an error message.

Request syntax
GET /session/1/session
Cookie: isisessid=12345678-abcd-1234-abcd-1234567890ab 
Response body

If authorization is successful:

"username": <string>
"services": [<string>, ...]  
"timeout_absolute": <integer>,  
"timeout_inactive": <integer> 

{
   "services":[
      "platform",
      "namespace"
   ],
   "timeout_absolute":14396,
   "timeout_inactive":900,
   "username":"user123"
}

If authorization fails:

401 Unauthorized
Content-Type: application/json
{
   "errors":[
      {
         "message":"authorization required"
      }
   ]
}
Log out of a session

If you no longer need to stay authenticated to a node, you can log out of a session by deleting the session cookie. Session cookies are configured to expire automatically in 15 minutes after a period of inactivity or in 4 hours after an absolute period of time.

Request syntax
DELETE /session/1/session 
Cookie: isisessid=12345678-abcd-1234-abcd-1234567890ab
Response body

If authorization is successful:

204 No Content
Set-Cookie:isisessid=deleted; path=/; Expires=Thu, 01-Jan-1970 00:00:01 GMT; HttpOnly; Secure
Content-Length: 0

If authorization fails:

401 Unauthorized
Content-Type: application/json
{
   "errors":[
      {
         "message":"authorization required"
      }
   ]
}