HTTP Verbs

The Oracle FS System RESTful API uses HTTP to implement REST. The RESTful API supports the following four HTTP verbs: GET, POST, PUT, and DELETE. The GET, PUT, and DELETE verbs observe all HTTP semantics, such as idempotency.

GET

Use the GET request to return one or more resources. If you do not provide the ID or the FQN in the request, only the ID and the FQN of all instances of the specified resource_name are returned. If you provide the ID or the FQN, the details for the specified instance are returned.

For example, to get the ID and the FQN for each LUN in the Oracle FS System, specify the LUN resource without any ID or the FQN:

GET https://<oraclefs_ip_or_dns>:8085/v1/lun HTTP/1.1
Authentication: Basic <encoded username:password>
Accept:  text/xml
Content-Type:  text/xml

To get the details for a specific LUN, include its ID or FQN, for example,

GET https://<oraclefs_ip_or_dns>:8085/v1/lun/\/LUN_123 HTTP/1.1
Authentication: Basic <encoded username:password>
Accept:  text/xml
Content-Type:  text/xml

Note: The leading slash is escaped with a backslash.

If additional options are required to qualify the information being returned about the resource, provide the options at the end of the URI as a query string (as CGI parameters). For example, use the following request to get all of the offline volumes associated with a drive group:

GET https://<oraclefs_ip_or_dns>:8085/v1/enclosure/%5C/ENCLOSURE-01?drivesmartdata=0 HTTP/1.1
Authentication: Basic <encoded username:password>
Accept:  text/xml
Content-Type:  text/xml

The GET request is always idempotent.

POST

Use the POST request to create a resource or to issue a command.

When the POST request is used to create a resource, the ID or the FQN is not required in the URI. Instead, provide a message body with the minimum set of options required to create the resource.

The following example creates a LUN using the POST request:

POST https://<oraclefs_ip_or_dns>:8085/v1/lun HTTP/1.1 
Authentication: Basic <encoded username:password>
Accept:  text/xml
Content-Type:  text/xml
<RequestBody>
  <name>lun1</name>
  <addressableCapacity>100</addressableCapacity>
  <priority>medium</priority>
  <storageClass>hddLff</storageClass> 
</RequestBody>

When the POST request is used to issue a command, the ID or the FQN is optional in the URI depending on the command being performed. The name of the command is included in the URI after the ID or the FQN. If the ID or the FQN is not required, the forward slash is still required. The message body is optional depending on the command. If the message body is provided, ensure that it contains any options needed by the command.

The following example requests a scan of a specific filesystem using the POST request:

POST https://<oraclefs_ip_or_dns>:8085/v1/filesystem/<id>/scan HTTP/1.1

The following example restarts the Oracle FS System using the POST request.

Note: The ID is empty and the message body contains the additional options for the restart.

POST https://<oraclefs_ip_or_dns>:8085/v1/system//restart HTTP/1.1
Authentication: Basic <encoded username:password>
Accept:  text/xml
Content-Type:  text/xml
<RequestBody>
	<serviceType>sanBias</serviceType>
  <overridePinnedData>1</overridePinnedData>
</RequestBody>

PUT

Use the PUT request to modify an existing resource or to modify global settings. If a resource is being modified, provide the ID or the FQN. The message body must be provided with the properties that are to be changed. The FSCLI option that identifies the ID or the FQN of the resource itself cannot be included in the message body and causes the request to fail with an HTTP return code of 400 (Bad Request).

The following example modifies the name of a LUN and Volume Group:

PUT https://<oraclefs_ip_or_dns>:8085/v1/lun/<id-of-lun> HTTP/1.1
Authentication: Basic <encoded username:password>
Accept:  text/xml
Content-Type:  text/xml
<RequestBody>
	<name>newName</name>
	<VolumeGroup>/otherVolGrp</VolumeGroup>
</RequestBody>

The following example modifies the global name of the Oracle FS System:

PUT https://<oraclefs_ip_or_dns>:8085/v1/system HTTP/1.1
Authentication: Basic <encoded username:password>
Accept:  text/xml
Content-Type:  text/xml
<RequestBody>
	<name>newOraclefsName</name>
</RequestBody>

The PUT request is idempotent except in the following cases:

The FQN is used to identify the resource
The name of the resource is being modified
The FQN of the resource is composed using its name

DELETE

Use the DELETE request to delete either a specific resource instance or multiple resource instances. To delete a specific resource instance, provide the ID or the FQN of the resource. To delete multiple instances, instead of providing the ID or the FQN in the URI, include a message body that specifies one or more options that identify the instances to be deleted. The location in the URI where the ID or the FQN would normally be put is left blank. Several FSCLI commands provide alternative options for identifying a set of instances to delete. You specify those alternative options in the message body.

The following example deletes a specific LUN:

DELETE https://<oraclefs_ip_or_dns>:8085/v1/lun/<id-of-lun> HTTP/1.1
Authentication: Basic <encoded username:password>
Accept:  text/xml
Content-Type:  text/xml

The following example deletes multiple NFS exports that are accessible through a File Server.

DELETE https://<oraclefs_ip_or_dns>:8085/v1/nfs_export HTTP/1.1
Authentication: Basic <encoded username:password>
Accept:  text/xml
Content-Type:  text/xml
<RequestBody>
  <fileServer>/server1</fileServer>
</RequestBody>