Getting Started with the Oracle ZFS Storage Appliance RESTful API

RESTful API Authentication

The Oracle ZFS Storage Appliance RESTful API uses the same authentication credentials as the browser user interface (BUI) and the command-line interface (CLI). All requests from external clients are individually authenticated using the appliance credentials and are conducted over an HTTPS connection on port 215. The RESTful API supports definable timeouts for HTTPS sessions.

Authentication can take one of the following forms:

Basic authentication – Each request must contain the user login. The authorization string is the concatenation username:password that is then Base64 encoded.

Example HTTP Header:
```
Authorization: Basic Tm8gcGVla2luZyE=
```
User authentication – BUI or CLI login credentials are used for authentication. In this case, the X-Auth-User header must contain the login name, and the X-Auth-Key header must contain the login password.

Example HTTP Headers:
```
X-Auth-User:  login-name
X-Auth-Key:  password-xxx
```
When the RADIUS service is configured, all directory users must be authenticated through RADIUS. However, the Oracle ZFS Storage Appliance RESTful API does not support authentication sequences that require multiple prompts and responses, such as a password, a challenge, and a response to the challenge. Note that REST login tokens can be used to bypass this authentication.

The appliance’s BUI and CLI interfaces fully support RADIUS multi-factor authentication for directory users. For more information, see RADIUS Configuration in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x.
Token authentication – When a token has been authenticated, a token header can be used to continue to run commands until the token expires. After a token expires, authentication must be done again before commands are accepted.

Example Token Header:
```
X-Auth-Session: qYftpufrrTxlDztkMhllLoyTfSDUSIR
```

RESTful API Versions

The RESTful API version for a given release of Oracle ZFS Storage Appliance has a global version number that matches the appliance software version. This version number is returned in the response header of all requests:

X-Zfssa-Version:  nas.2013.1.1

RESTful API Service Versions

Each RESTful API service has a version number as part of the Uniform Resource Identifier (URI) to access the service. The version has a major and minor number. Requests must supply the major version number, but the minor version number is optional and defaults to a value of 0 if not supplied. The major number must match the major number of the service. The minor number must be less than or equal to the minor number of the service.

For example, the following table shows whether the specified versions could be used in a client request if the client is requesting a service that is running version 2.1.

Request Version	Allowed
`1`	No: Major version does not match the version the service is running
`2`	Yes: Major version matches, and the minor version (default `0`) is backward compatible
`2.1`	Yes: Major and minor version values match the version the service is running
`2.2`	No: Major version matches, but the minor version is newer than the version the service is running

No service API version changes are required for the following property changes. The Oracle ZFS Storage Appliance version number and model must be used to determine which properties are available. These property changes are also reflected in the CLI and BUI and are an indication of the capabilities of that appliance instance.

New output properties (without removing old properties).
New input properties added to an existing command, that have default values that make the command behave is it did in an earlier version.

Since a newer version of a backwards-compatible command can return additional properties, clients should be coded to ignore new properties. The minor number is incremented for backwards-compatible changes to the service API.

Add a new command to an existing service.
Add new query parameters to service commands.

The major number is incremented with incompatible changes to the service API.

Removing command query parameters.
Removing a command from an existing service.

Major releases of appliance software may include incompatible version changes. There may or may not be older versions of a given service during a major update. Each command response must contain an HTTP header with the current version of the appliance API for a given module:

X-Zfssa-Nas-Api:  1.1

Common RESTful Operations

The following table shows the common RESTful operations for a given resource.

Table 1-1 Common RESTful Operations

Request	Path	Description
GET	resources	List all resources
GET	resources/name	Get a JSON object describing the selected resource
POST	resources	Create a new resource
PUT	resources/name	Modify the selected resource
DELETE	resources/name	Delete the selected resource

HTTP Response Body

All response data is encoded in JSON format as defined by RFC 4627. Unless otherwise specified, commands against a single resource return a single JSON results object with the resource name as a property. Each command section documents which property names are returned in this JSON result object.

Unless otherwise stated, the create (POST) and modify (PUT) commands return the properties of the created or modified resource. The contents should match the values returned by the GET request.

Example Body:

{
    "resource_name": {
        "href": "path/to/this/resource",
        "property_01": "value_01",
        "property_02": "value_01
    }
}

Some GET commands return a list of resources.

{
    "resource_list_name": [
        {
            "href": "path/to/resource_01",
            "property_01": "value_01"
        }, {
            "href": "path/to/resource_02",
            "property_02", "value_02"
        }
    ]
}

Note:

Throughout this document, commands show JSON return results that have been formatted by adding returns and spaces to make it more readable. The actual output does not contain this formatting.

HTTP Response Headers

All Oracle ZFS Storage Appliance service commands that send data use the JSON data format and require the following header values:

Accept:  application/json
Content-Type:  application/json

Response Headers include the following information:

Date: Tue, 23 Jul 2013 13:07:37 GMT X-Zfs-Sa-Appliance-Api: 1.0 Content-Type: application/json Content-Length: 357

For list results, the content length may not be known before data is sent back. If the content length is not supplied, the client must read the response body until EOF to read all the returned data.

Appliance Errors

Errors return an HTTP status code that indicates the error along with the following fault response payload.

JSON Fault Response:

{
    fault: {
        message: 'ERR_INVALID_ARG',
        details: 'Error Details...',
        code: 500
    }
}

Table 1-2 Common Error Codes

Error	Code	Description
ERR_INVALID_ARG	400	Invalid input argument
ERR_UNKNOWN_ARG	400	Extra unhandled input argument
ERR_MISSING_ARG	400	Required input argument missing
ERR_UNAUTHORIZED	401	This user is not authorized to execute command
ERR_DENIED	403	Operation denied
ERR_STATE_CHANGED		Conflict in system state
ERR_NOT_FOUND	404	The requested item was not found
ERR_OBJECT_EXISTS	409	Request creates an object that already exists
ERR_CONFIRM_REQUIRED	409	Request requires the `?confirm=true` query parameter to complete
ERR_OVER_LIMIT	413	Input request too large to handle
ERR_UNSUPPORTED_MEDIA	415	Requested media type is not supported by request
ERR_NOT_IMPLEMENTED	501	Operation not implemented
ERR_BUSY	503	Service not available due to limited resources

Security Protocols and Ciphers Settings

The protocol version and associated cipher commands manage the SSL/TLS protocol versions and ciphers for accessing Oracle ZFS Storage Appliance.

By default, SSL/TLS protocol versions TLSv1.1, TLSv1.2 and their associated ciphers are enabled. You can enable TLSv1.0 by sending a PUT request to the HTTPS service to set the tls_version property.

Example Request:

PUT /api/service/v1/services/https HTTP/1.1
Host: zfs-storage.example.com:215
Content-Type: application/json

{ "tls_version":  ["TLSv1.0", "TLSv1.1", "TLSv1.2"] }

Example Result (output is omitted for brevity):

HTTP/1.1 202 Accepted
Content-Length: 1265
X-Zfssa-Service-Api: 1.1
X-Zfssa-Api-Version: 1.0
Content-Type: application/json; charset=utf-8

{
  "service": {
    "href": "/api/service/v1/services/https",
    "<status>": "online",
    "tls_version": "TLSv1 TLSv1.1 TLSv1.2",
    "ciphers": "SRP-DSS-AES-256-CBC-SHA:SRP-RSA-AES-256-CBC-SHA:SRP-AES-256-CBC-SHA:
    ...
    3DES-EDE-CBC-SHA:EDH-RSA-DES-CBC3-SHA:EDH-DSS-DES-CBC3-SHA:DH-RSA-DES-CBC3-SHA:
    DH-DSS-DES-CBC3-SHA:DES-CBC3-SHA"
  }
}

To enable TLSv1.0 only, set the ciphers property to the list of ciphers available for TLSv1.0 only.

Example Request (output is omitted for brevity):

PUT /api/service/v1/services/https HTTP/1.1
Host: zfs-storage.example.com:215
Content-Type: application/json

{
  "tls_version":  ["TLSv1.0"] , 
  "ciphers" : ["SRP-DSS-AES-256-CBC-SHA", "SRP-RSA-AES-256-CBC-SHA", "SRP-AES-256-CBC-SHA",
  ...
  "EDH-RSA-DES-CBC3-SHA", "EDH-DSS-DES-CBC3-SHA", "DH-RSA-DES-CBC3-SHA", "DH-DSS-DES-CBC3-SHA",
  "DES-CBC3-SHA"] 
}

Example Result (output is omitted for brevity):

HTTP/1.1 202 Accepted
Content-Length: 809
X-Zfssa-Service-Api: 1.1
X-Zfssa-Api-Version: 1.0
Content-Type: application/json; charset=utf-8

{
  "service": {
    "href": "/api/service/v1/services/https",
    "<status>": "online", "tls_version": "TLSv1",
    "ciphers": "SRP-DSS-AES-256-CBC-SHA:SRP-RSA-AES-256-CBC-SHA:SRP-AES-256-CBC-SHA:
    ...
    3DES-EDE-CBC-SHA:SRP-3DES-EDE-CBC-SHA:EDH-RSA-DES-CBC3-SHA:EDH-DSS-DES-CBC3-SHA:DH-
    RSA-DES-CBC3-SHA:DH-DSS-DES-CBC3-SHA:DES-CBC3-SHA"
  }
}

Note:

To avoid being blocked from using the RESTful API or the BUI, keep the default settings for the tls_version and ciphers properties unless otherwise needed or as instructed by Oracle Support.

Session Timeout

The HTTPS service controls the session timeout, which specifies the number of minutes until the browser automatically logs out of the session after user inactivity or if the user navigates away from the BUI. The default value is 15 minutes. This replaces the session timeout property previously located in the user preferences area of the software.

To set the value to other than 15 minutes, send a PUT request to the HTTPS service, and set the session_timeout property to a different value.

Example Request:

PUT /api/service/v1/services/https HTTP/1.1
Host: zfs-storage.example.com:215
Content-Type: application/json

{ "session_timeout":  5 }

Example Result:

HTTP/1.1 202 Accepted
Content-Length: 1265
X-Zfssa-Service-Api: 1.1
X-Zfssa-Api-Version: 1.0
Content-Type: application/json; charset=utf-8

{
  "service": {
    "href": "/api/service/v1/services/https",
    "<status>": "online",
    "tls_version": "default",
    "permit_root_login": true,
    "session_timeout": 5,
    "hsts_enable": false,
    "hsts_max_age": 63072000
  }
}

Password Complexity

The password RESTful API enables a user who has the changeProperties authorization to set password complexity rules for all local users. For information about user authorizations, see RESTful API Role Service.

Password requirements are enforced when local users change their passwords. Existing passwords are not affected by password rule changes.

Use the following command to show the properties that can be changed.

Example Request:

GET /api/setting/v2/password HTTP/1.1
Host: zfs-storage.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: application/json

Example Result:

HTTP/1.1 200 OK
Date: Fri, 14 May 2021 17:07:39 GMT
Content-Type: application/json; charset=utf-8
X-Zfssa-Api-Version: 2.0
X-Zfssa-Setting-Api: 2.0
Content-Length: 196

{
  "complexity": {
    "href": "/api/setting/v2/password",
    "passlength": 8,
    "min_letters": 0,
    "min_upper": 0,
    "min_lower": 0,
    "min_digit": 0,
    "min_punctuation": 0,
    "max_repeats": 0,
    "namecheck": true
  }
}

For descriptions of these properties, see Password Complexity Properties in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x.

The following example changes the password rules to require at least one each of upper case letter, lower case letter, number, and punctuation character. The min_letters value must be updated to account for the new min_upper and min_lower values.

Example Request:

PUT /api/setting/v2/password HTTP/1.1
Host: zfs-storage.example.com:215
Content-Type: application/json

{"min_letters": 2, "min_upper": 1, "min_lower": 1, "min_digit": 1, "min_punctuation": 1}

Example Result:

HTTP/1.1 202 Accepted
Date: Fri, 14 May 2021 17:38:40 GMT
Content-Type: application/json; charset=utf-8
X-Zfssa-Api-Version: 2.0
X-Zfssa-Setting-Api: 2.0
Content-Length: 196

{
  "complexity": {
    "href": "/api/setting/v2/password",
    "passlength": 8,
    "min_letters": 2,
    "min_upper": 1,
    "min_lower": 1,
    "min_digit": 1,
    "min_punctuation": 1,
    "max_repeats": 0,
    "namecheck": true
  }
}