Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License. See accompanying LICENSE file.
-->
Ozone REST API's.
===================
<!-- MACRO{toc|fromDepth=0|toDepth=1} -->
Overview
--------
The Ozone REST API's allows user to access ozone via REST protocol.
Authentication and Authorization
--------------------
For time being, The default authentication mode of REST API is insecure access
mode, which is *Simple* mode. Under this mode, ozone server trusts the user
name specified by client and it does not perform any authentication.
User name can be specified in HTTP header by
*`x-ozone-user: {USER_NAME}`
for example if add following header *x-ozone-user: bilbo* in the HTTP request,
then operation will be executed as *bilbo* user.
In *Simple* mode, there is no real authorization either. Client can be
authorized to obtain administrator privilege by using HTTP header
*`Authorization: {AUTH_METHOD} {SIGNATURE}`
for example set following header *Authorization: OZONE root* in the HTTP request,
then ozone will authorize the client with administrator privilege.
Common REST Headers
--------------------
The following HTTP headers must be set for each REST call.
| Property | Description |
|:---- |:----
| Authorization | The authorization field determines which authentication method is used by ozone. Currently only *simple* mode is supported, the corresponding value is *OZONE*. Optionally an user name can be set as *OZONE {USER_NAME}* to authorize as a particular user. |
| Date | Standard HTTP header that represents dates. The format is - day of the week, month, day, year and time (military time format) in GMT. Any other time zone will be rejected by ozone server. Eg. *Date : Mon, Apr 4, 2016 06:22:00 GMT*. This field is required. |
| x-ozone-version | A required HTTP header to indicate which version of API this call will be communicating to. E.g *x-ozone-version: v1*. Currently ozone only publishes v1 version API. |
Common Reply Headers
--------------------
The common reply headers are part of all Ozone server replies.
| Property | Description |
|:---- |:----
| Date | This is the HTTP date header and it is set to server’s local time expressed in GMT. |
| x-ozone-request-id | This is a UUID string that represents an unique request ID. This ID is used to track the request through the ozone system and is useful for debugging purposes. |
| x-ozone-server-name | Fully qualified domain name of the sever which handled the request. |
Volume APIs
--------------------
### Create a Volume
This API allows admins to create a new storage volume.
this request creates a volume as user *bilbo*, the authorization field is set to *OZONE root* because this call requires administration privilege. The client receives a response with zero content length.
This API allows administrators to update volume info such as ownership and quota. This API requires administration privilege.
Schema:
-`PUT /{volume}?quota=<VOLUME_QUOTA>`
Query Parameter:
| Query Parameter | Value | Description |
|:---- |:---- |:----
| quota | long<BYTES \| MB \| GB \| TB> \| remove | Optional. Quota size in BYTEs, MBs, GBs or TBs. Or use string value *remove* to remove an existing quota for a volume. |
this request gets all volumes owned by *bilbo* and each volume's name contains prefix *Jan*, the result at most contains *100* entries. The client receives a list of SON objects, each of them describes the info of a volume.
this request adds an ACL policy specified by HTTP header *x-ozone-acl* to bucket */volume-of-bilbo/bucket-to-update*, the ACL field *ADD user:peregrin:rw* gives add additional read/write permission to user *peregrin* to this bucket.
Deletes a bucket if it is empty. An user can only delete bucket owned by themselves, and administrators can delete buckets owned by any user, as long as it is empty.
this request lists all the buckets under volume *volume-of-bilbo*, and the result at most contains 10 entries. The client receives response of a array of JSON objects, each of them represents for a bucket info.
this request uploads a local file */path/to/localfile* specified by option *-T* to ozone as user *bilbo*, mapped to ozone key */volume-of-bilbo/bucket-0/file-0*. The client receives a zero length content response.
### Get Key
This API allows user to get or download a key from an ozone bucket.
this request reads the content of key */volume-of-bilbo/bucket-0/file-0*. If the content of the file is plain text, it can be directly dumped onto stdout.
if the file is not plain text, specify *-O* option in curl command and the file *file-0* will be downloaded into current working directory, file name will be same as the key. A sample request like following:
this request list keys under bucket */volume-of-bilbo/bucket-0*, the listing result is filtered by prefix *file*. The client receives an array of JSON objects, each of them represents the info of a matched key.
