Oracle FS System RESTful API Request Format

An Oracle FS System RESTful API request consists of the HTTP verb (GET, POST, PUT, or DELETE), a URI identifying a resource or set of resources, HTTP header field values, and an optional message body.

URI Format

The following example is the URI format for the Oracle FS System RESTful API HTTP verbs.

https:⁠//<oraclefs_ip_or_dns>:8085⁠/v⁠1/<resource_name>⁠[/ID or FQN⁠][/<subcommand>]

The optional ID or FQN values identify a specific resource instance and are provided based on the HTTP verb used. When specifying an FQN, escape the leading slash (/) with a backslash (\).

Only use the optional /subcommand value with the POST command to issue subcommands.

HTTP Header Fields

You can specify the HTTP Content-Type, Accept, and Authentication header field values in the Oracle FS System RESTful API request. The Content-Type field specifies the format of the message body included in the request. The Accept field specifies the message body format of the response. The two values supported for the Content-Type and the Accept fields are text/xml for XML formatting and text/json for JSON formatting. The Oracle FS System RESTful API supports basic authorization over HTTPS with each command execution.

Message Body

When the Oracle FS System RESTful API request is either a POST or a PUT, include a message body. When the RESTful API request is a DELETE request that deletes more than one resource, include a message body with the DELETE request to specify the criteria used for selecting the resources. Message bodies may be either an XML format or a JSON format.

The following example is a text/xml Content-Type message body.

<RequestBody>
  One or more element tags that map to FSCLI option names and values.
<⁠/RequestBody>

A direct one‑to‑one mapping of FSCLI command options to the element tag names and values that are in the message body exists. Responses might contain a message body. The Accept HTTP header specifies the format for the contents in the message body.

The following example is a text/xml Content-Type response message body:

<RequestBody>
  One or more element tags containing FSCLI XML tags and values.
<⁠/RequestBody>

In the cases where prompt responses are required, respond to the prompt, and then resend the request with the prompt response in the request body. If there are multiple prompts required, the RESTful interface returns a failed response with a new prompt and the ID number of the failed response. Resend the previous command, appending another <PromptResponse> section until you finally send a request that has all the prompt responses accounted for.

The following example demonstrates a request that failed because it needed the user to reply to a prompt:

Note: See the following lines in the example:

<PromptRequired>Warning: Lun "414B303032323736A104781007D6A8DE" has clones, if you
continue, they will all be deleted. If just a specific clone is
to be deleted, use clone_lun -delete.
Continue(y/N)? </PromptRequired>

Example

DELETE https://<oraclefs_ip_or_dns>:8085/v1/lun/414B303032323736A104781007D6A8DE
Authentication: Basic <encoded username:password> 
Content-type:text/xml

HTTP/1.1 409 Conflict
Date: Thu, 19 Mar 2015 22:04:56 GMT
Server: Apache/2.2.15 (Oracle)
Connection: close
Transfer-Encoding: chunked
Content-Type: text/xml

<?xml version="1.0"?>
<ResponseBody>
<CLIResponse>
<ResponseHeader>
<ClientData>FSCLI</ClientData>
<Command>lun</Command>
</ResponseHeader>
<PromptRequired>Warning: Lun "414B303032323736A104781007D6A8DE" has clones, if you
continue, they will all be deleted. If just a specific clone is
to be deleted, use clone_lun -delete.
Continue(y/N)? </PromptRequired>
<PromptId>1</PromptId>
</CLIResponse>
</ResponseBody>

The following example demonstrates a resend of the request with the prompt response in the request body:

Note: See the following lines in the example:

<RequestBody><PromptResponse><id>1</id><response>y</response></PromptResponse></RequestBody>

Example

DELETE https://<oraclefs_ip_or_dns>:8085/v1/lun/414B303032323736A104781007D6A8DE
Authentication: Basic <encoded username:password> 
Content-type:text/xml

<RequestBody><PromptResponse><id>1</id><response>y</response></PromptResponse></RequestBody>

HTTP/1.1 200 OK
Connection: close
Date: Thu, 19 Mar 2015 22:04:56 GMT
Server: Apache/2.2.15 (Oracle)
Content-Type: text/xml

<?xml version="1.0"?>
<ResponseBody>
<CLIResponse>
  <ResponseHeader>
    <ClientData>FSCLI</ClientData>
    <Command>lun</Command>
  </ResponseHeader>
<TaskInformation>
  <TaskGuid>414B303032323736A13FC165BBA5CA84</TaskGuid>
  <TaskFqn>/DeleteLun/4416770/administrator</TaskFqn>
</TaskInformation>
<Status>succeeded</Status>
</CLIResponse>
</ResponseBody>