<commit_before>---
layout: global
title: S3 Client
nickname: S3 Client
group: Clients
priority: 3
---

Alluxio supports a RESTFul API that is compatible with the basic operations of the Amazon 
[S3 API](http://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html).

The [REST API documentation](http://www.alluxio.org/restdoc/{{site.ALLUXIO_MAJOR_VERSION}}/proxy/index.html)
is generated as part of Alluxio build and accessible through
`${ALLUXIO_HOME}/core/server/proxy/target/miredot/index.html`.

There are performance implications of using the HTTP proxy. In particular, using the proxy requires
an extra hop. For optimal performance, it is recommended to run the proxy server and an Alluxio
worker on each compute node.

# Features support
The following table describes the support status for current Amazon S3 functional features:

<table class="table table-striped">
<tr><th>S3 Feature</th><th>Status</th></tr>
{% for item in site.data.table.s3-api-supported-operations %}
  <tr>
    <td>{{ item.S3Feature }}</td>
    <td>{{ item.Status }}</td>
  </tr>
{% endfor %}
</table>

# Example Usage

## Rest API
For example, you can run the following RESTFul API calls to an Alluxio cluster running on localhost.
The Alluxio proxy is listening at port 39999 by default.

### Create a bucket

```bash
# curl -i -X PUT http://localhost:39999/api/v1/s3/testbucket
HTTP/1.1 200 OK
Date: Tue, 29 Aug 2017 22:34:41 GMT
Content-Length: 0
Server: Jetty(9.2.z-SNAPSHOT)
```

### Get the bucket (listing objects)

```bash
# curl -i -X GET http://localhost:39999/api/v1/s3/testbucket
HTTP/1.1 200 OK
Date: Tue, 29 Aug 2017 22:35:00 GMT
Content-Type: application/xml
Content-Length: 200
Server: Jetty(9.2.z-SNAPSHOT)

<ListBucketResult xmlns=""><Name>/testbucket</Name><Prefix/><ContinuationToken/><NextContinuationToken/><KeyCount>0</KeyCount><MaxKeys>1000</MaxKeys><IsTruncated>false</IsTruncated></ListBucketResult>
```

### Put an object
Assume there is an existing file on local file system called `LICENSE`.<commit_msg>Add languages support section<commit_after>---
layout: global
title: S3 Client
nickname: S3 Client
group: Clients
priority: 3
---

Alluxio supports a RESTFul API that is compatible with the basic operations of the Amazon 
[S3 API](http://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html).

The [REST API documentation](http://www.alluxio.org/restdoc/{{site.ALLUXIO_MAJOR_VERSION}}/proxy/index.html)
is generated as part of Alluxio build and accessible through
`${ALLUXIO_HOME}/core/server/proxy/target/miredot/index.html`.

There are performance implications of using the HTTP proxy. In particular, using the proxy requires
an extra hop. For optimal performance, it is recommended to run the proxy server and an Alluxio
worker on each compute node.

# Features support
The following table describes the support status for current Amazon S3 functional features:

<table class="table table-striped">
<tr><th>S3 Feature</th><th>Status</th></tr>
{% for item in site.data.table.s3-api-supported-operations %}
  <tr>
    <td>{{ item.S3Feature }}</td>
    <td>{{ item.Status }}</td>
  </tr>
{% endfor %}
</table>

# Language support
Alluxio S3 client supports various programming languages, such as C++, Java, Python, Golang, Ruby and etc.
In this documentation, we use curl Rest calls and python S3 client as usage examples.

# Example Usage

## Rest API
For example, you can run the following RESTFul API calls to an Alluxio cluster running on localhost.
The Alluxio proxy is listening at port 39999 by default.

### Create a bucket

```bash
# curl -i -X PUT http://localhost:39999/api/v1/s3/testbucket
HTTP/1.1 200 OK
Date: Tue, 29 Aug 2017 22:34:41 GMT
Content-Length: 0
Server: Jetty(9.2.z-SNAPSHOT)
```

### Get the bucket (listing objects)

```bash
# curl -i -X GET http://localhost:39999/api/v1/s3/testbucket
HTTP/1.1 200 OK
Date: Tue, 29 Aug 2017 22:35:00 GMT
Content-Type: application/xml
Content-Length: 200
Server: Jetty(9.2.z-SNAPSHOT)

<ListBucketResult xmlns=""><Name>/testbucket</Name><Prefix/><ContinuationToken/><NextContinuationToken/><KeyCount>0</KeyCount><MaxKeys>1000</MaxKeys><IsTruncated>false</IsTruncated></ListBucketResult>
```

### Put an object
Assume there is an existing file on local file system called `LICENSE`.
{'fraction_non_alphanumeric': 0.12244418331374853, 'fraction_numerical': 0.03572267920094007, 'mean_word_length': 4.743589743589744, 'pattern_counts': {'":': 0, '<': 57, '<?xml version=': 0, '>': 57, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 4}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '880522', 'n_tokens_mistral': 1478, 'n_tokens_neox': 1338, 'n_words': 463}