| |
| |
| <!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="#sidebar" 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 hidden-xs" href="#">Apache Hadoop Ozone/HDDS documentation</a> |
| <a class="navbar-brand visible-xs-inline" href="#">Hadoop Ozone</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" id="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="./s3.html">S3</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 & 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> |
| |
| |
| <li class="visible-xs"><a href="#">References</a> |
| <ul class="nav"> |
| <li><a href="https://github.com/apache/hadoop"><span class="glyphicon glyphicon-new-window" aria-hidden="true"></span> Source</a></li> |
| <li><a href="https://hadoop.apache.org"><span class="glyphicon glyphicon-new-window" aria-hidden="true"></span> Apache Hadoop</a></li> |
| <li><a href="https://apache.org"><span class="glyphicon glyphicon-new-window" aria-hidden="true"></span> ASF</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’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=<VOLUME_QUOTA></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 "x-ozone-user: bilbo" -H "x-ozone-version: v1" -H "Date: Mon, 26 Jun 2017 04:23:30 GMT" -H "Authorization:OZONE root" "http://localhost:9880/volume-to-create" |
| </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=<VOLUME_QUOTA></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 "Authorization:OZONE root" -H "Date: Mon, 26 Jun 2017 04:23:30 GMT" -H "x-ozone-version: v1" -H "x-ozone-user: john" 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 "Authorization:OZONE root" -H "Date: Mon, 26 Jun 2017 04:23:30 GMT" -H "x-ozone-version: v1" -H "x-ozone-user: bilbo" 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">“volume”</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 "x-ozone-user: bilbo" -H "x-ozone-version: v1" -H "Date: Mon, 26 Jun 2017 04:23:30 GMT" -H "Authorization:OZONE" "http://localhost:9880/volume-of-bilbo?info=volume" |
| </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 |
| |
| { |
| "owner" : { "name" : "bilbo" }, |
| "quota" : { "unit" : "TB", "size" : 1048576 }, |
| "volumeName" : "volume-of-bilbo", |
| "createdOn" : "Tue, 27 Jun 2017 07:42:04 GMT", |
| "createdBy" : "root" |
| } |
| </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=<PREFIX>&max-keys=<MAX_RESULT_SIZE>&prev-key=<PREVIOUS_VOLUME_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">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 "x-ozone-user: bilbo" -H "x-ozone-version: v1" -H "Date: Mon, 26 Jun 2017 04:23:30 GMT" -H "Authorization:OZONE" "http://localhost:9880/?max-keys=100&prefix=Jan" |
| </code></pre> |
| |
| <p>this request gets all volumes owned by <em>bilbo</em> and each volume’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 |
| |
| { |
| "volumes" : [ |
| { |
| "owner" : { "name" : "bilbo"}, |
| "quota" : { "unit" : "TB", "size" : 2 }, |
| "volumeName" : "Jan-vol1", |
| "createdOn" : "Tue, 27 Jun 2017 07:42:04 GMT", |
| "createdBy" : 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 "x-ozone-user: bilbo" -H "x-ozone-version: v1" -H "Date: Mon, 26 Jun 2017 04:23:30 GMT" -H "Authorization:OZONE" 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 "x-ozone-user: bilbo" -H "x-ozone-version: v1" -H "Date: Mon, 26 Jun 2017 04:23:30 GMT" -H "Authorization:OZONE" -H "x-ozone-acl: ADD user:peregrin:rw" 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 "Authorization:OZONE root" -H "Date: Mon, 26 Jun 2017 04:23:30 GMT" -H "x-ozone-version: v1" -H "x-ozone-user:bilbo" "http://localhost:9880/volume-of-bilbo/bucket-0" |
| </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">“bucket”</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 "x-ozone-user: bilbo" -H "x-ozone-version: v1" -H "Date: Mon, 26 Jun 2017 04:23:30 GMT" -H "Authorization:OZONE" "http://localhost:9880/volume-of-bilbo/bucket-0?info=bucket" |
| </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 |
| |
| { |
| "volumeName" : "volume-of-bilbo", |
| "bucketName" : "bucket-0", |
| "createdOn" : "Tue, 27 Jun 2017 08:55:25 GMT", |
| "acls" : [ ], |
| "versioning" : "DISABLED", |
| "storageType" : "DISK" |
| } |
| </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=<PREFIX>&max-keys=<MAX_RESULT_SIZE>&prev-key=<PREVIOUS_BUCKET_KEY></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 "x-ozone-user: bilbo" -H "x-ozone-version: v1" -H "Date: Mon, 26 Jun 2017 04:23:30 GMT" -H "Authorization:OZONE" "http://localhost:9880/volume-of-bilbo?max-keys=10" |
| </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 |
| |
| { |
| "buckets" : [ { |
| "volumeName" : "volume-of-bilbo", |
| "bucketName" : "bucket-0", |
| "createdOn" : "Tue, 27 Jun 2017 08:55:25 GMT", |
| "acls" : [ ], |
| "versioning" : null, |
| "storageType" : "DISK", |
| "bytesUsed" : 0, |
| "keyCount" : 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 "Authorization:OZONE" -H "Date: Mon, 26 Jun 2017 04:23:30 GMT" -H "x-ozone-version: v1" -H "x-ozone-user:bilbo" "http://localhost:9880/volume-of-bilbo/bucket-0/file-0" |
| </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 "x-ozone-user: bilbo" -H "x-ozone-version: v1" -H "Date: Mon, 26 Jun 2017 04:23:30 GMT" -H "Authorization:OZONE" "http://localhost:9880/volume-of-bilbo/bucket-0/file-0" |
| </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 "x-ozone-user: bilbo" -H "x-ozone-version: v1" -H "Date: Mon, 26 Jun 2017 04:23:30 GMT" -H "Authorization:OZONE" "http://localhost:9880/volume-of-bilbo/bucket-0/file-1" |
| </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 "Authorization:OZONE root" -H "Date: Mon, 26 Jun 2017 04:23:30 GMT" -H "x-ozone-version: v1" -H "x-ozone-user:bilbo" "http://localhost:9880/volume-of-bilbo/bucket-0/file-0" |
| </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, “key”</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 "x-ozone-user: bilbo" -H "x-ozone-version: v1" -H "Date: Mon, 26 Jun 2017 04:23:30 GMT" -H "Authorization:OZONE" "http://localhost:9880/volume-of-bilbo/buket-0/file-0?info=key" |
| </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 |
| |
| { |
| "version" : 0, |
| "md5hash" : null, |
| "createdOn" : "Mon, 26 Jun 2017 04:23:30 GMT", |
| "modifiedOn" : "Mon, 26 Jun 2017 04:23:30 GMT", |
| "size" : 0, |
| "keyName" : "file-0" |
| } |
| </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=<PREFIX>&max-keys=<MAX_RESULT_SIZE>&prev-key=<PREVIOUS_KEY></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 "x-ozone-user: bilbo" -H "x-ozone-version: v1" -H "Date: Mon, 26 Jun 2017 04:23:30 GMT" -H "Authorization:OZONE" "http:/localhost:9880/volume-of-bilbo/bucket-0/?max-keys=100&prefix=file" |
| </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 |
| |
| { |
| "name" : null, |
| "prefix" : file, |
| "maxKeys" : 0, |
| "truncated" : false, |
| "keyList" : [ { |
| "version" : 0, |
| "md5hash" : null, |
| "createdOn" : "Mon, 26 Jun 2017 04:23:30 GMT", |
| "modifiedOn" : "Mon, 26 Jun 2017 04:23:30 GMT", |
| "size" : 0, |
| "keyName" : "file-0" |
| }, |
| ... |
| ] |
| } |
| </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> |