Google Git
Sign in
apache / ozone-site / c29b914fd984c4ce59cf535d5f8f442407e798b3 / . / docs / 0.2.1-alpha / rest.html
blob: 601d206cbf463639bb3be03d1a1319710679ce6d [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="Hadoop Ozone Documentation">
<title>Documentation for Apache Hadoop Ozone</title>
<link href="css/bootstrap.min.css" rel="stylesheet">
<link href="css/ozonedoc.css" rel="stylesheet">
</head>
<body>
<nav class="navbar navbar-inverse navbar-fixed-top">
<div class="container-fluid">
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="#">Apache Hadoop Ozone/HDDS documentation</a>
</div>
<div id="navbar" class="navbar-collapse collapse">
<ul class="nav navbar-nav navbar-right">
<li><a href="https://github.com/apache/hadoop">Source</a></li>
<li><a href="https://hadoop.apache.org">Apache Hadoop</a></li>
<li><a href="https://apache.org">ASF</a></li>
</ul>
</div>
</div>
</nav>
<div class="container-fluid">
<div class="row">
<div class="col-sm-3 col-md-2 sidebar">
<img src="ozone-logo.png" style="max-width: 100%;"/>
<ul class="nav nav-sidebar">
<li class="">
<a href="index.html">
<span>Ozone Overview</span>
</a>
</li>
<li class="">
<a href="runningviadocker.html">
<span>Getting Started</span>
</a>
<ul class="nav">
<li class="">
<a href="./runningviadocker.html">Alpha Cluster</a>
</li>
<li class="">
<a href="./settings.html">Configuration</a>
</li>
<li class="">
<a href="./realcluster.html">Starting an Ozone Cluster</a>
</li>
<li class="">
<a href="./runningwithhdfs.html">Running concurrently with HDFS</a>
</li>
<li class="">
<a href="./buildingsources.html">Building from Sources</a>
</li>
</ul>
</li>
<li class="">
<a href="commandshell.html">
<span>Client</span>
</a>
<ul class="nav">
<li class="">
<a href="./commandshell.html">Ozone CLI</a>
</li>
<li class="">
<a href="./volumecommands.html">Volume Commands</a>
</li>
<li class="">
<a href="./bucketcommands.html">Bucket Commands</a>
</li>
<li class="">
<a href="./keycommands.html">Key Commands</a>
</li>
<li class="">
<a href="./javaapi.html">Java API</a>
</li>
<li class="">
<a href="./ozonefs.html">Ozone File System</a>
</li>
<li class="active">
<a href="./rest.html">REST API</a>
</li>
</ul>
</li>
<li class="">
<a href="dozone.html">
<span>Tools</span>
</a>
<ul class="nav">
<li class="">
<a href="./dozone.html">Dozone &amp; Dev Tools</a>
</li>
<li class="">
<a href="./freon.html">Freon</a>
</li>
<li class="">
<a href="./scmcli.html">SCMCLI</a>
</li>
</ul>
</li>
<li class="">
<a href="./concepts.html">
<span>Architecture</span>
</a>
<ul class="nav">
<li class="">
<a href="./hdds.html">Hadoop Distributed Data Store</a>
</li>
<li class="">
<a href="./ozonemanager.html">Ozone Manager</a>
</li>
</ul>
</li>
</ul>
</div>
<div class="col-sm-9 col-sm-offset-3 col-md-10 col-md-offset-2 main">
<h1>REST API</h1>
<div class="col-md-9">
<!---
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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.
-->
<p>The Ozone REST API&rsquo;s allows user to access ozone via REST protocol.</p>
<h2 id="authentication-and-authorization">Authentication and Authorization</h2>
<p>For time being, The default authentication mode of REST API is insecure access
mode, which is <em>Simple</em> mode. Under this mode, ozone server trusts the user
name specified by client and it does not perform any authentication.</p>
<p>User name can be specified in HTTP header by</p>
<ul>
<li><code>x-ozone-user: {USER_NAME}</code></li>
</ul>
<p>for example if add following header <em>x-ozone-user: bilbo</em> in the HTTP request,
then operation will be executed as <em>bilbo</em> user.
In <em>Simple</em> mode, there is no real authorization either. Client can be
authorized to obtain administrator privilege by using HTTP header</p>
<ul>
<li><code>Authorization: {AUTH_METHOD} {SIGNATURE}</code></li>
</ul>
<p>for example set following header <em>Authorization: OZONE root</em> in the HTTP request,
then ozone will authorize the client with administrator privilege.</p>
<h2 id="common-rest-headers">Common REST Headers</h2>
<p>The following HTTP headers must be set for each REST call.</p>
<table>
<thead>
<tr>
<th align="left">Property</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">Authorization</td>
<td align="left">The authorization field determines which authentication method is used by ozone. Currently only <em>simple</em> mode is supported, the corresponding value is <em>OZONE</em>. Optionally an user name can be set as <em>OZONE {USER_NAME}</em> to authorize as a particular user.</td>
</tr>
<tr>
<td align="left">Date</td>
<td align="left">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. <em>Date : Mon, Apr 4, 2016 06:22:00 GMT</em>. This field is required.</td>
</tr>
<tr>
<td align="left">x-ozone-version</td>
<td align="left">A required HTTP header to indicate which version of API this call will be communicating to. E.g <em>x-ozone-version: v1</em>. Currently ozone only publishes v1 version API.</td>
</tr>
</tbody>
</table>
<h2 id="common-reply-headers">Common Reply Headers</h2>
<p>The common reply headers are part of all Ozone server replies.</p>
<table>
<thead>
<tr>
<th align="left">Property</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">Date</td>
<td align="left">This is the HTTP date header and it is set to server’s local time expressed in GMT.</td>
</tr>
<tr>
<td align="left">x-ozone-request-id</td>
<td align="left">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.</td>
</tr>
<tr>
<td align="left">x-ozone-server-name</td>
<td align="left">Fully qualified domain name of the sever which handled the request.</td>
</tr>
</tbody>
</table>
<h2 id="volume-apis">Volume APIs</h2>
<h3 id="create-a-volume">Create a Volume</h3>
<p>This API allows admins to create a new storage volume.</p>
<p>Schema:</p>
<ul>
<li><code>POST /{volume}?quota=&lt;VOLUME_QUOTA&gt;</code></li>
</ul>
<p>Query Parameter:</p>
<table>
<thead>
<tr>
<th align="left">Query Parameter</th>
<th align="left">Value</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">quota</td>
<td align="left">long<BYTES \| MB \| GB \| TB></td>
<td align="left">Optional. Quota size in BYTEs, MBs, GBs or TBs</td>
</tr>
</tbody>
</table>
<p>Sample HTTP POST request:</p>
<pre><code>curl -i -X POST -H &quot;x-ozone-user: bilbo&quot; -H &quot;x-ozone-version: v1&quot; -H &quot;Date: Mon, 26 Jun 2017 04:23:30 GMT&quot; -H &quot;Authorization:OZONE root&quot; &quot;http://localhost:9880/volume-to-create&quot;
</code></pre>
<p>this request creates a volume as user <em>bilbo</em>, the authorization field is set to <em>OZONE root</em> because this call requires administration privilege. The client receives a response with zero content length.</p>
<pre><code>HTTP/1.1 201 Created
x-ozone-server-name: localhost
x-ozone-request-id: 2173deb5-bbb7-4f0a-8236-f354784e3bae
Date: Tue, 27 Jun 2017 07:42:04 GMT
Content-Type: application/octet-stream
Content-Length: 0
Connection: keep-alive
</code></pre>
<h3 id="update-volume">Update Volume</h3>
<p>This API allows administrators to update volume info such as ownership and quota. This API requires administration privilege.</p>
<p>Schema:</p>
<ul>
<li><code>PUT /{volume}?quota=&lt;VOLUME_QUOTA&gt;</code></li>
</ul>
<p>Query Parameter:</p>
<table>
<thead>
<tr>
<th align="left">Query Parameter</th>
<th align="left">Value</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">quota</td>
<td align="left">long<BYTES \| MB \| GB \| TB> | remove</td>
<td align="left">Optional. Quota size in BYTEs, MBs, GBs or TBs. Or use string value <em>remove</em> to remove an existing quota for a volume.</td>
</tr>
</tbody>
</table>
<p>Sample HTTP PUT request:</p>
<pre><code>curl -X PUT -H &quot;Authorization:OZONE root&quot; -H &quot;Date: Mon, 26 Jun 2017 04:23:30 GMT&quot; -H &quot;x-ozone-version: v1&quot; -H &quot;x-ozone-user: john&quot; http://localhost:9880/volume-to-update
</code></pre>
<p>this request modifies the owner of <em>/volume-to-update</em> to <em>john</em>.</p>
<h3 id="delete-volume">Delete Volume</h3>
<p>This API allows user to delete a volume owned by themselves if the volume is not empty. Administrators can delete volumes owned by any user.</p>
<p>Schema:</p>
<ul>
<li><code>DELETE /{volume}</code></li>
</ul>
<p>Sample HTTP DELETE request:</p>
<pre><code>curl -i -X DELETE -H &quot;Authorization:OZONE root&quot; -H &quot;Date: Mon, 26 Jun 2017 04:23:30 GMT&quot; -H &quot;x-ozone-version: v1&quot; -H &quot;x-ozone-user: bilbo&quot; http://localhost:9880/volume-to-delete
</code></pre>
<p>this request deletes an empty volume <em>/volume-to-delete</em>. The client receives a zero length content.</p>
<pre><code>HTTP/1.1 200 OK
x-ozone-server-name: localhost
x-ozone-request-id: 6af14c64-e3a9-40fe-9634-df60b7cbbc6a
Date: Tue, 27 Jun 2017 08:49:52 GMT
Content-Type: application/octet-stream
Content-Length: 0
Connection: keep-alive
</code></pre>
<h3 id="info-volume">Info Volume</h3>
<p>This API allows user to read the info of a volume owned by themselves. Administrators can read volume info owned by any user.</p>
<p>Schema:</p>
<ul>
<li><code>GET /{volume}?info=volume</code></li>
</ul>
<p>Query Parameter:</p>
<table>
<thead>
<tr>
<th align="left">Query Parameter</th>
<th align="left">Value</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">info</td>
<td align="left">&ldquo;volume&rdquo;</td>
<td align="left">Required and enforced with this value.</td>
</tr>
</tbody>
</table>
<p>Sample HTTP GET request:</p>
<pre><code>curl -i -H &quot;x-ozone-user: bilbo&quot; -H &quot;x-ozone-version: v1&quot; -H &quot;Date: Mon, 26 Jun 2017 04:23:30 GMT&quot; -H &quot;Authorization:OZONE&quot; &quot;http://localhost:9880/volume-of-bilbo?info=volume&quot;
</code></pre>
<p>this request gets the info of volume <em>/volume-of-bilbo</em>, the client receives a response with a JSON object of volume info.</p>
<pre><code>HTTP/1.1 200 OK
x-ozone-server-name: localhost
x-ozone-request-id: a2224806-beaf-42dd-a68e-533cd7508f74
Date: Tue, 27 Jun 2017 07:55:35 GMT
Content-Type: application/octet-stream
Content-Length: 171
Connection: keep-alive
{
&quot;owner&quot; : { &quot;name&quot; : &quot;bilbo&quot; },
&quot;quota&quot; : { &quot;unit&quot; : &quot;TB&quot;, &quot;size&quot; : 1048576 },
&quot;volumeName&quot; : &quot;volume-of-bilbo&quot;,
&quot;createdOn&quot; : &quot;Tue, 27 Jun 2017 07:42:04 GMT&quot;,
&quot;createdBy&quot; : &quot;root&quot;
}
</code></pre>
<h3 id="list-volumes">List Volumes</h3>
<p>This API allows user to list all volumes owned by themselves. Administrators can list all volumes owned by any user.</p>
<p>Schema:</p>
<ul>
<li><code>GET /?prefix=&lt;PREFIX&gt;&amp;max-keys=&lt;MAX_RESULT_SIZE&gt;&amp;prev-key=&lt;PREVIOUS_VOLUME_KEY&gt;</code></li>
</ul>
<p>Query Parameter:</p>
<table>
<thead>
<tr>
<th align="left">Query Parameter</th>
<th align="left">Value</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">prefix</td>
<td align="left">string</td>
<td align="left">Optional. Only volumes with this prefix are included in the result.</td>
</tr>
<tr>
<td align="left">max-keys</td>
<td align="left">int</td>
<td align="left">Optional. Maximum number of volumes included in the result. Default is 1024 if not specified.</td>
</tr>
<tr>
<td align="left">prev-key</td>
<td align="left">string</td>
<td align="left">Optional. Volume name from where listing should start, this key is excluded in the result. It must be a valid volume name.</td>
</tr>
<tr>
<td align="left">root-scan</td>
<td align="left">bool</td>
<td align="left">Optional. List all volumes in the cluster if this is set to true. Default false.</td>
</tr>
</tbody>
</table>
<p>Sample HTTP GET request:</p>
<pre><code>curl -i -H &quot;x-ozone-user: bilbo&quot; -H &quot;x-ozone-version: v1&quot; -H &quot;Date: Mon, 26 Jun 2017 04:23:30 GMT&quot; -H &quot;Authorization:OZONE&quot; &quot;http://localhost:9880/?max-keys=100&amp;prefix=Jan&quot;
</code></pre>
<p>this request gets all volumes owned by <em>bilbo</em> and each volume&rsquo;s name contains prefix <em>Jan</em>, the result at most contains <em>100</em> entries. The client receives a list of SON objects, each of them describes the info of a volume.</p>
<pre><code>HTTP/1.1 200 OK
x-ozone-server-name: localhost
x-ozone-request-id: 7fa0dce1-a8bd-4387-bc3c-1dac4b710bb1
Date: Tue, 27 Jun 2017 08:07:04 GMT
Content-Type: application/octet-stream
Content-Length: 602
Connection: keep-alive
{
&quot;volumes&quot; : [
{
&quot;owner&quot; : { &quot;name&quot; : &quot;bilbo&quot;},
&quot;quota&quot; : { &quot;unit&quot; : &quot;TB&quot;, &quot;size&quot; : 2 },
&quot;volumeName&quot; : &quot;Jan-vol1&quot;,
&quot;createdOn&quot; : &quot;Tue, 27 Jun 2017 07:42:04 GMT&quot;,
&quot;createdBy&quot; : root
},
...
]
}
</code></pre>
<h2 id="bucket-apis">Bucket APIs</h2>
<h3 id="create-bucket">Create Bucket</h3>
<p>This API allows an user to create a bucket in a volume.</p>
<p>Schema:</p>
<ul>
<li><code>POST /{volume}/{bucket}</code></li>
</ul>
<p>Additional HTTP Headers:</p>
<table>
<thead>
<tr>
<th align="left">HTTP Header</th>
<th align="left">Value</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">x-ozone-acl</td>
<td align="left">ozone ACLs</td>
<td align="left">Optional. Ozone acls.</td>
</tr>
<tr>
<td align="left">x-ozone-storage-class</td>
<td align="left"><DEFAULT \| ARCHIVE \| DISK \| RAM_DISK \| SSD ></td>
<td align="left">Optional. Storage type for a volume.</td>
</tr>
<tr>
<td align="left">x-ozone-bucket-versioning</td>
<td align="left">enabled/disabled</td>
<td align="left">Optional. Do enable bucket versioning or not.</td>
</tr>
</tbody>
</table>
<p>Sample HTTP POST request:</p>
<pre><code>curl -i -X POST -H &quot;x-ozone-user: bilbo&quot; -H &quot;x-ozone-version: v1&quot; -H &quot;Date: Mon, 26 Jun 2017 04:23:30 GMT&quot; -H &quot;Authorization:OZONE&quot; http://localhost:9880/volume-of-bilbo/bucket-0
</code></pre>
<p>this request creates a bucket <em>bucket-0</em> under volume <em>volume-of-bilbo</em>.</p>
<pre><code>HTTP/1.1 201 Created
x-ozone-server-name: localhost
x-ozone-request-id: 49acfeec-4c85-470a-872b-2eaebd8d751e
Date: Tue, 27 Jun 2017 08:55:25 GMT
Content-Type: application/octet-stream
Content-Length: 0
Connection: keep-alive
</code></pre>
<h3 id="update-bucket">Update Bucket</h3>
<p>Updates bucket meta-data, like ACLs.</p>
<p>Schema:</p>
<ul>
<li><code>PUT /{volume}/{bucket}</code></li>
</ul>
<p>Additional HTTP Headers:</p>
<table>
<thead>
<tr>
<th align="left">HTTP Header</th>
<th align="left">Value</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">x-ozone-acl</td>
<td align="left">ozone ACLs</td>
<td align="left">Optional. Ozone acls.</td>
</tr>
<tr>
<td align="left">x-ozone-bucket-versioning</td>
<td align="left">enabled/disabled</td>
<td align="left">Optional. Do enable bucket versioning or not.</td>
</tr>
</tbody>
</table>
<p>Sample HTTP PUT request:</p>
<pre><code>curl -i -X PUT -H &quot;x-ozone-user: bilbo&quot; -H &quot;x-ozone-version: v1&quot; -H &quot;Date: Mon, 26 Jun 2017 04:23:30 GMT&quot; -H &quot;Authorization:OZONE&quot; -H &quot;x-ozone-acl: ADD user:peregrin:rw&quot; http://localhost:9880/volume-of-bilbo/bucket-to-update
</code></pre>
<p>this request adds an ACL policy specified by HTTP header <em>x-ozone-acl</em> to bucket <em>/volume-of-bilbo/bucket-to-update</em>, the ACL field <em>ADD user:peregrin:rw</em> gives add additional read/write permission to user <em>peregrin</em> to this bucket.</p>
<pre><code>HTTP/1.1 200 OK
x-ozone-server-name: localhost
x-ozone-request-id: b061a295-5faf-4b98-94b9-8b3e87c8eb5e
Date: Tue, 27 Jun 2017 09:02:37 GMT
Content-Type: application/octet-stream
Content-Length: 0
Connection: keep-alive
</code></pre>
<h3 id="delete-bucket">Delete Bucket</h3>
<p>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.</p>
<p>Schema:</p>
<ul>
<li><code>DELETE /{volume}/{bucket}</code></li>
</ul>
<p>Sample HTTP DELETE request:</p>
<pre><code>curl -i -X DELETE -H &quot;Authorization:OZONE root&quot; -H &quot;Date: Mon, 26 Jun 2017 04:23:30 GMT&quot; -H &quot;x-ozone-version: v1&quot; -H &quot;x-ozone-user:bilbo&quot; &quot;http://localhost:9880/volume-of-bilbo/bucket-0&quot;
</code></pre>
<p>this request deletes bucket <em>/volume-of-bilbo/bucket-0</em>. The client receives a zero length content response.</p>
<pre><code>HTTP/1.1 200 OK
x-ozone-server-name: localhost
x-ozone-request-id: f57acd7a-2116-4c2f-aa2f-5a483db81c9c
Date: Tue, 27 Jun 2017 09:16:52 GMT
Content-Type: application/octet-stream
Content-Length: 0
Connection: keep-alive
</code></pre>
<h3 id="info-bucket">Info Bucket</h3>
<p>This API returns information about a given bucket.</p>
<p>Schema:</p>
<ul>
<li><code>GET /{volume}/{bucket}?info=bucket</code></li>
</ul>
<p>Query Parameters:</p>
<table>
<thead>
<tr>
<th align="left">Query Parameter</th>
<th align="left">Value</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">info</td>
<td align="left">&ldquo;bucket&rdquo;</td>
<td align="left">Required and enforced with this value.</td>
</tr>
</tbody>
</table>
<p>Sample HTTP GET request:</p>
<pre><code>curl -i -H &quot;x-ozone-user: bilbo&quot; -H &quot;x-ozone-version: v1&quot; -H &quot;Date: Mon, 26 Jun 2017 04:23:30 GMT&quot; -H &quot;Authorization:OZONE&quot; &quot;http://localhost:9880/volume-of-bilbo/bucket-0?info=bucket&quot;
</code></pre>
<p>this request gets the info of bucket <em>/volume-of-bilbo/bucket-0</em>. The client receives a response of JSON object contains bucket info.</p>
<pre><code>HTTP/1.1 200 OK
x-ozone-server-name: localhost
x-ozone-request-id: f125485b-8cae-4c7f-a2d6-5b1fefd6f193
Date: Tue, 27 Jun 2017 09:08:31 GMT
Content-Type: application/json
Content-Length: 138
Connection: keep-alive
{
&quot;volumeName&quot; : &quot;volume-of-bilbo&quot;,
&quot;bucketName&quot; : &quot;bucket-0&quot;,
&quot;createdOn&quot; : &quot;Tue, 27 Jun 2017 08:55:25 GMT&quot;,
&quot;acls&quot; : [ ],
&quot;versioning&quot; : &quot;DISABLED&quot;,
&quot;storageType&quot; : &quot;DISK&quot;
}
</code></pre>
<h3 id="list-buckets">List Buckets</h3>
<p>List buckets in a given volume.</p>
<p>Schema:</p>
<ul>
<li><code>GET /{volume}?prefix=&lt;PREFIX&gt;&amp;max-keys=&lt;MAX_RESULT_SIZE&gt;&amp;prev-key=&lt;PREVIOUS_BUCKET_KEY&gt;</code></li>
</ul>
<p>Query Parameters:</p>
<table>
<thead>
<tr>
<th align="left">Query Parameter</th>
<th align="left">Value</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">prefix</td>
<td align="left">string</td>
<td align="left">Optional. Only buckets with this prefix are included in the result.</td>
</tr>
<tr>
<td align="left">max-keys</td>
<td align="left">int</td>
<td align="left">Optional. Maximum number of buckets included in the result. Default is 1024 if not specified.</td>
</tr>
<tr>
<td align="left">prev-key</td>
<td align="left">string</td>
<td align="left">Optional. Bucket name from where listing should start, this key is excluded in the result. It must be a valid bucket name.</td>
</tr>
</tbody>
</table>
<p>Sample HTTP GET request:</p>
<pre><code>curl -i -H &quot;x-ozone-user: bilbo&quot; -H &quot;x-ozone-version: v1&quot; -H &quot;Date: Mon, 26 Jun 2017 04:23:30 GMT&quot; -H &quot;Authorization:OZONE&quot; &quot;http://localhost:9880/volume-of-bilbo?max-keys=10&quot;
</code></pre>
<p>this request lists all the buckets under volume <em>volume-of-bilbo</em>, 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.</p>
<pre><code>HTTP/1.1 200 OK
x-ozone-server-name: localhost
x-ozone-request-id: e048c3d5-169c-470f-9903-632d9f9e32d5
Date: Tue, 27 Jun 2017 09:12:18 GMT
Content-Type: application/octet-stream
Content-Length: 207
Connection: keep-alive
{
&quot;buckets&quot; : [ {
&quot;volumeName&quot; : &quot;volume-of-bilbo&quot;,
&quot;bucketName&quot; : &quot;bucket-0&quot;,
&quot;createdOn&quot; : &quot;Tue, 27 Jun 2017 08:55:25 GMT&quot;,
&quot;acls&quot; : [ ],
&quot;versioning&quot; : null,
&quot;storageType&quot; : &quot;DISK&quot;,
&quot;bytesUsed&quot; : 0,
&quot;keyCount&quot; : 0
},
...
]
}
</code></pre>
<h2 id="key-apis">Key APIs</h2>
<h3 id="put-key">Put Key</h3>
<p>This API allows user to create or overwrite keys inside of a bucket.</p>
<p>Schema:</p>
<ul>
<li><code>PUT /{volume}/{bucket}/{key}</code></li>
</ul>
<p>Additional HTTP headers:</p>
<table>
<thead>
<tr>
<th align="left">HTTP Header</th>
<th align="left">Value</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">Content-MD5</td>
<td align="left">MD5 digest</td>
<td align="left">Standard HTTP header, file hash.</td>
</tr>
</tbody>
</table>
<p>Sample PUT HTTP request:</p>
<pre><code>curl -X PUT -T /path/to/localfile -H &quot;Authorization:OZONE&quot; -H &quot;Date: Mon, 26 Jun 2017 04:23:30 GMT&quot; -H &quot;x-ozone-version: v1&quot; -H &quot;x-ozone-user:bilbo&quot; &quot;http://localhost:9880/volume-of-bilbo/bucket-0/file-0&quot;
</code></pre>
<p>this request uploads a local file <em>/path/to/localfile</em> specified by option <em>-T</em> to ozone as user <em>bilbo</em>, mapped to ozone key <em>/volume-of-bilbo/bucket-0/file-0</em>. The client receives a zero length content response.</p>
<h3 id="get-key">Get Key</h3>
<p>This API allows user to get or download a key from an ozone bucket.</p>
<p>Schema:</p>
<ul>
<li><code>GET /{volume}/{bucket}/{key}</code></li>
</ul>
<p>Sample HTTP GET request:</p>
<pre><code>curl -i -H &quot;x-ozone-user: bilbo&quot; -H &quot;x-ozone-version: v1&quot; -H &quot;Date: Mon, 26 Jun 2017 04:23:30 GMT&quot; -H &quot;Authorization:OZONE&quot; &quot;http://localhost:9880/volume-of-bilbo/bucket-0/file-0&quot;
</code></pre>
<p>this request reads the content of key <em>/volume-of-bilbo/bucket-0/file-0</em>. If the content of the file is plain text, it can be directly dumped onto stdout.</p>
<pre><code>HTTP/1.1 200 OK
Content-Type: application/octet-stream
x-ozone-server-name: localhost
x-ozone-request-id: 1bcd7de7-d8e3-46bb-afee-bdc933d383b8
Date: Tue, 27 Jun 2017 09:35:29 GMT
Content-Length: 6
Connection: keep-alive
Hello Ozone!
</code></pre>
<p>if the file is not plain text, specify <em>-O</em> option in curl command and the file <em>file-0</em> will be downloaded into current working directory, file name will be same as the key. A sample request like following:</p>
<pre><code>curl -O -i -H &quot;x-ozone-user: bilbo&quot; -H &quot;x-ozone-version: v1&quot; -H &quot;Date: Mon, 26 Jun 2017 04:23:30 GMT&quot; -H &quot;Authorization:OZONE&quot; &quot;http://localhost:9880/volume-of-bilbo/bucket-0/file-1&quot;
</code></pre>
<p>response looks like following:</p>
<pre><code>% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 6148k 100 6148k 0 0 24.0M 0 --:--:-- --:--:-- --:--:-- 24.1M
</code></pre>
<h3 id="delete-key">Delete Key</h3>
<p>This API allows user to delete a key from a bucket.</p>
<p>Schema:</p>
<ul>
<li><code>DELETE /{volume}/{bucket}/{key}</code></li>
</ul>
<p>Sample HTTP DELETE request:</p>
<pre><code>curl -i -X DELETE -H &quot;Authorization:OZONE root&quot; -H &quot;Date: Mon, 26 Jun 2017 04:23:30 GMT&quot; -H &quot;x-ozone-version: v1&quot; -H &quot;x-ozone-user:bilbo&quot; &quot;http://localhost:9880/volume-of-bilbo/bucket-0/file-0&quot;
</code></pre>
<p>this request deletes key <em>/volume-of-bilbo/bucket-0/file-0</em>. The client receives a zero length content result:</p>
<pre><code>HTTP/1.1 200 OK
x-ozone-server-name: localhost
x-ozone-request-id: f8c4a373-dd5f-4e3a-b6c4-ddf7e191fe91
Date: Tue, 27 Jun 2017 14:19:48 GMT
Content-Type: application/octet-stream
Content-Length: 0
Connection: keep-alive
</code></pre>
<h3 id="info-key">Info Key</h3>
<p>This API returns information about a given key.</p>
<p>Schema:</p>
<ul>
<li><code>GET /{volume}/{bucket}/{key}?info=key</code></li>
</ul>
<p>Query Parameter:</p>
<table>
<thead>
<tr>
<th align="left">Query Parameter</th>
<th align="left">Value</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">info</td>
<td align="left">String, &ldquo;key&rdquo;</td>
<td align="left">Required and enforced with this value.</td>
</tr>
</tbody>
</table>
<p>Sample HTTP DELETE request:</p>
<pre><code>curl -i -H &quot;x-ozone-user: bilbo&quot; -H &quot;x-ozone-version: v1&quot; -H &quot;Date: Mon, 26 Jun 2017 04:23:30 GMT&quot; -H &quot;Authorization:OZONE&quot; &quot;http://localhost:9880/volume-of-bilbo/buket-0/file-0?info=key&quot;
</code></pre>
<p>this request returns information of the key <em>/volume-of-bilbo/bucket-0/file-0</em>. The client receives a JSON object listed attributes of the key.</p>
<pre><code>HTTP/1.1 200 OK
x-ozone-server-name: localhost
x-ozone-request-id: c674343c-a0f2-49e4-bbd6-daa73e7dc131
Date: Mon, 03 Jul 2017 14:28:45 GMT
Content-Type: application/octet-stream
Content-Length: 73
Connection: keep-alive
{
&quot;version&quot; : 0,
&quot;md5hash&quot; : null,
&quot;createdOn&quot; : &quot;Mon, 26 Jun 2017 04:23:30 GMT&quot;,
&quot;modifiedOn&quot; : &quot;Mon, 26 Jun 2017 04:23:30 GMT&quot;,
&quot;size&quot; : 0,
&quot;keyName&quot; : &quot;file-0&quot;
}
</code></pre>
<h3 id="list-keys">List Keys</h3>
<p>This API allows user to list keys in a bucket.</p>
<p>Schema:</p>
<ul>
<li><code>GET /{volume}/{bucket}?prefix=&lt;PREFIX&gt;&amp;max-keys=&lt;MAX_RESULT_SIZE&gt;&amp;prev-key=&lt;PREVIOUS_KEY&gt;</code></li>
</ul>
<p>Query Parameters:</p>
<table>
<thead>
<tr>
<th align="left">Query Parameter</th>
<th align="left">Value</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">prefix</td>
<td align="left">string</td>
<td align="left">Optional. Only keys with this prefix are included in the result.</td>
</tr>
<tr>
<td align="left">max-keys</td>
<td align="left">int</td>
<td align="left">Optional. Maximum number of keys included in the result. Default is 1024 if not specified.</td>
</tr>
<tr>
<td align="left">prev-key</td>
<td align="left">string</td>
<td align="left">Optional. Key name from where listing should start, this key is excluded in the result. It must be a valid key name.</td>
</tr>
</tbody>
</table>
<p>Sample HTTP GET request:</p>
<pre><code>curl -i -H &quot;x-ozone-user: bilbo&quot; -H &quot;x-ozone-version: v1&quot; -H &quot;Date: Mon, 26 Jun 2017 04:23:30 GMT&quot; -H &quot;Authorization:OZONE&quot; &quot;http:/localhost:9880/volume-of-bilbo/bucket-0/?max-keys=100&amp;prefix=file&quot;
</code></pre>
<p>this request list keys under bucket <em>/volume-of-bilbo/bucket-0</em>, the listing result is filtered by prefix <em>file</em>. The client receives an array of JSON objects, each of them represents the info of a matched key.</p>
<pre><code>HTTP/1.1 200 OK
x-ozone-server-name: localhost
x-ozone-request-id: 7f9fc970-9904-4c56-b671-83a086c6f555
Date: Tue, 27 Jun 2017 09:48:59 GMT
Content-Type: application/json
Content-Length: 209
Connection: keep-alive
{
&quot;name&quot; : null,
&quot;prefix&quot; : file,
&quot;maxKeys&quot; : 0,
&quot;truncated&quot; : false,
&quot;keyList&quot; : [ {
&quot;version&quot; : 0,
&quot;md5hash&quot; : null,
&quot;createdOn&quot; : &quot;Mon, 26 Jun 2017 04:23:30 GMT&quot;,
&quot;modifiedOn&quot; : &quot;Mon, 26 Jun 2017 04:23:30 GMT&quot;,
&quot;size&quot; : 0,
&quot;keyName&quot; : &quot;file-0&quot;
},
...
]
}
</code></pre>
</div>
</div>
</div>
</div>
<script src="./js/jquery.min.js"></script>
<script src="./js/ozonedoc.js"></script>
<script src="./js/bootstrap.min.js"></script>
</body>
</html>