Oracle ZFS Storage Appliance RESTful API Support for the Oracle Cloud Infrastructure Object Storage Service

The following RESTful API requests support the Oracle Cloud Infrastructure Object Storage service.

Table 1-1 RESTful API services Commands to Support the Oracle Cloud Infrastructure Object Storage Service

Request	Append to Path /api/service/v2/services	Description
GET	/http	List http service and sub-service details.
GET	/http/oci	List the Oracle Cloud Infrastructure service details.
PUT	/http/oci	Modify the Oracle Cloud Infrastructure service.
GET	/http/oci/keys	List all Oracle Cloud Infrastructure public keys.
POST	/http/oci/keys	Create a new Oracle Cloud Infrastructure public key.
GET	/http/oci/keys/user/fingerprint	List the specified Oracle Cloud Infrastructure public key.
DELETE	/http/oci/keys/user/fingerprint	Delete the specified Oracle Cloud Infrastructure public key.

Table 1-2 RESTful API pools Commands to Support the Oracle Cloud Infrastructure Object Storage Service

Request	Append to Path /api/storage/v2/pools	Description
GET	/pool/projects/project	List project details, including the value of the shareoci property.
GET	/pool/projects/project/filesystems/filesystem	List filesystem details, including the value of the shareoci property.
PUT	/pool/projects/project	Set the shareoci property for the specified project.
PUT	/pool/projects/project/filesystems/filesystem	Set the shareoci property for the specified filesystem.

List Oracle Cloud Infrastructure Service Details

The following example lists all properties and sub-services of the HTTP service.

Example Request:

GET /api/service/v2/services/http

Example Result:

Some details are omitted from the following output.

{
  "service": {
    "href": "/api/service/v2/services/http",
    ...
    "oci": {
      "href": "/api/service/v2/services/http/oci",
      "oci_enabled": false,
      "oci_default_path": "",
      "keys": [ ... ]
    },
    "s3": { ... },
    "swift": { ... },
    "webdav": { ... }
  }
}

The following example lists all properties of the HTTP Oracle Cloud Infrastructure service.

Example Request:

GET /api/service/v2/services/http/oci

Example Result:

{
  "oci": {
    "href": "/api/service/v2/services/http/oci",
    "oci_enabled": false,
    "oci_default_path": "",
    "keys": [
      {
        "user": "user1",
        "comment": "comment"
        "fingerprint": "fingerprint1",
        "href": "/api/service/v2/services/http/oci/keys/user1/fingerprint1"
      },
      {
        "user": "user2",
        "comment": "comment"
        "fingerprint": "fingerprint2",
        "href": "/api/service/v2/services/http/oci/keys/user2/fingerprint2"
      }
    ]
  }
}

Enable the Oracle Cloud Infrastructure Service

Example Request:

PUT /api/service/v2/services/http/oci

{ "oci_enabled": true }

Example Result:

{
  "oci": {
    "href": "/api/service/v2/services/http/oci",
    "oci_enabled": true,
    "oci_default_path": "",
    "keys": [ ... ]
  }
}

The oci_default_path property specifies the default location to store your objects. This default path is used if you do not specify the location for an object when you use the Oracle Cloud Infrastructure object store.

The value of this property is the mountpoint of a filesystem that has the shareoci property set to rw as described in Set the Oracle Cloud Infrastructure Default Path.

List Oracle Cloud Infrastructure Keys

The following example lists all Oracle Cloud Infrastructure keys.

Example Request:

GET /api/service/v2/services/http/oci/keys

Example Result:

"keys": [
  {
    "user": "user1",
    "comment": "comment"
    "fingerprint": "fingerprint1",
    "href": "/api/service/v2/services/http/oci/keys/user1/fingerprint1"
  },
  {
    "user": "user2",
    "comment": "comment"
    "fingerprint": "fingerprint2",
    "href": "/api/service/v2/services/http/oci/keys/user2/fingerprint2"
  }
]

The following example lists the specified Oracle Cloud Infrastructure key.

Example Request:

GET /api/service/v2/services/http/oci/user2/fingerprint2

Example Result:

{
  "key": {
    "user": "user2",
    "comment": "comment",
    "fingerprint": "fingerprint2",
    "href": "/api/service/v2/services/http/oci/keys/user2/fingerprint2"
  }
}

Create a New Oracle Cloud Infrastructure User Key

To create a new user key, enter a user name, a public key, and an optional comment.

The user name is the OCID of an Oracle Cloud Infrastructure account user and is also a valid data user on the appliance. A data user is a user that is allowed to access data protocols. The user does not need to be an appliance administrator.

The public key is a 392-character base64 string that corresponds to an RSA public key in PEM format.

A unique fingerprint is generated for each different key that is entered by the same user.

The same fingerprint is generated for a key that is entered by different users, as shown in the following example.

Example Request:

POST /api/service/v2/services/http/oci/keys

{
    "user": "user3",
    "key" : "-----BEGIN PUBLIC KEY-----\\nkey2-text\\n-----END PUBLIC KEY-----",
    "comment": "comment"
}

Example Result:

{
  "key": {
    "user": "user3",
    "comment": "comment",
    "fingerprint": "fingerprint2",
    "href": "/api/service/v2/services/http/oci/keys/user3/fingerprint2"
  }
}

Change Operations Permissions for an Oracle Cloud Infrastructure User Key

Permissions control a user's ability to perform operations on resources. See the Permissions Required for Each API Operation for more information.

If a user attempts to perform an operation using a key that does not grant permission for that operation, HTTP status 401 (Unauthorized) is returned.

The following request shows the operations permissions for an Oracle Cloud Infrastructure user key.

Example Request:

GET /api/service/v2/services/http/oci/keys/user3/fingerprint2

Example Result:

{
  "key": {
    "href": "/api/service/v2/services/http/oci/keys/user3/fingerprint2",
    "user": "user3",
    "fingerprint": "fingerprint2",
    "comment": "",
    "namespace_read": true,
    "bucket_create": true,
    "bucket_update": true,
    "bucket_read": true,
    "bucket_inspect": true,
    "bucket_delete": true,
    "object_create": true,
    "object_overwrite": true,
    "object_read": true,
    "object_inspect": true,
    "object_delete": true,
    "object_version_delete": true,
    "par_manage": true,
    "retention_rule_manage": true,
    "retention_rule_lock": true
  }
}

The following example disables the object_delete and object_version_delete permissions for the user3/fingerprint2 key.

Example Request:

PUT /api/service/v2/services/http/oci/keys/user3/fingerprint2

{"object_delete": false, "object_version_delete": false}

Example Result:

{
  "key": {
    "href": "/api/service/v2/services/http/oci/keys/user3/fingerprint2",
    "user": "user3",
    "fingerprint": "fingerprint2",
    "comment": "",
    "namespace_read": true,
    "bucket_create": true,
    "bucket_update": true,
    "bucket_read": true,
    "bucket_inspect": true,
    "bucket_delete": true,
    "object_create": true,
    "object_overwrite": true,
    "object_read": true,
    "object_inspect": true,
    "object_delete": false,
    "object_version_delete": false,
    "par_manage": true,
    "retention_rule_manage": true,
    "retention_rule_lock": true
  }
}

Delete an Oracle Cloud Infrastructure User Key

Example Request:

DELETE /api/service/v2/services/http/oci/user2/fingerprint2

Set the Oracle Cloud Infrastructure Default Path

The default path is used by clients that access the object storage service and do not specify a namespace. See the oci_default_path property in Enable the Oracle Cloud Infrastructure Service. The value of the oci_default_path property is the mountpoint of a filesystem that has the shareoci property set to rw.

You can set the shareoci property on a project or on a filesystem. The shareoci property setting on a project is inherited by all child filesystems unless you explicitly set the property on the filesystem.

Note:

OCI API mode can be enabled only if no other share mode is enabled. If OCI API mode is enabled (the shareoci property is set to read/write for a filesystem), no other share mode can be enabled. OCI API mode cannot be disabled once it has been enabled.

The following example shows the value of the shareoci property on the proj1 project.

Example Request:

GET /api/storage/v2/pools/p1/projects/proj1 HTTP/1.1

Example Result:

{
  "project": {
    ...
    "shareoci": "off",
    ...
  }
}

The following example shows the value of the shareoci property on the f1 filesystem.

Example Request:

GET /api/storage/v2/pools/p1/projects/proj1/filesystems/f1 HTTP/1.1

Example Result:

{
  "filesystem": {
    ...
    "shareoci": "off",
    ...
  }
}

The following example sets the value of the shareoci property on the f1 filesystem.

Example Request:

PUT /api/storage/v2/pools/p1/projects/proj1/filesystems/f1 HTTP/1.1

{ "shareoci": "rw" }

Example Result:

{
  "filesystem": {
    ...
    "shareoci": "rw",
    ...
  }
}