2 Working with the RESTful API

The access service is the entry point for all RESTful API services on Oracle ZFS Storage Appliance. The service is used to authenticate user credentials and to list the available RESTful API services, including their versions and access points.

Accessing the Service

To access the service, use one of the following URLs:

• http://hostname:215/api/access/v2

• http://hostname:215/api/access/v1

To access other services, log in using the access service to get the location and versions of the available services and then use the returned URI to access those services. Service locations can change based on the current appliance configuration or release level.

Table 2-1 Access Service Commands

Request	Path	Description
GET	/api/access/v{1|2}	List RESTful API service access points
POST	/api/access/v{1|2}	Create a non-persistent login token
DELETE	/api/access/v{1|2}	Log out and delete a non-persistent login token

List Services

The list services command lists the available service access URIs. If a login session is not desired, list services can be used with appropriate credentials to list the available service access URIs. This command lists all the RESTful API services and versions available on Oracle ZFS Storage Appliance.

Example Request:

GET /api/access/v1 HTTP/1.1
Host: zfs-storage.example.com:215
X-Auth-User: admin1
X-Auth-Key: password

Example Result:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 190
X-Zfssa-Access-Api: 1.0

{
  "services": [
    {
      "version": "1.1",
      "name": "hardware",
      "uri": "https://hostname:215/api/hardware/v1"
    },
    {
      "version": "1.0",
      "name": "san",
      "uri": "https://hostname:215/api/san/v1"
    },
    {
      "version": "1.0",
      "name": "network",
      "uri": "https://hostname:215/api/network/v1"
    }
  ]
}

List Service Operations

This command returns the list of operations (methods) that are available for the specified service. If applicable, this command returns information about the resources of the specified service. In the following example, the cluster hardware component has resources that can be further examined and configured.

Example Request. Notice that this request uses an authentication token. See Authentication Tokens:

GET /api/hardware/v1 HTTP/1.1
Host: zfs-storage.example.com:215
X-Auth-Session: puPnHZKgSrUmXqYzOwFCrGcLOGwPODj

Example Result. For brevity, most of this output is omitted:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 204
X-Zfssa-Access-Api: 1.0

{
  "service": {
    "methods": [
      {
        "path": "",
        "href": "/api/hardware/v1",
        "request": "GET",
        "description": "List the hardware service commands."
      },
      {
        "path": "/cluster",
        "href": "/api/hardware/v1/cluster",
        "request": "GET",
        "description": "Get cluster properties and cluster resource list"
      },
      {
        "path": "/cluster/resources/<resource:path>",
        "href": "/api/hardware/v1/cluster/resources/<resource:path>",
        "request": "GET",
        "description": "Get properties for the specified cluster resource"
      },
      {
        "path": "/cluster/resources/<resource:path>",
        "href": "/api/hardware/v1/cluster/resources/<resource:path>",
        "request": "PUT",
        "description": "Modify the specified cluster resource"
      },
      {
        "path": "/chassis",
        "href": "/api/hardware/v1/chassis",
        "request": "GET",
        "description": "List hardware chassis"
      }
    ],
    "version": "1.1",
    "name": "hardware",
    "uri": "https://hostname:215/api/hardware/v1"
  }
}