# Alluxio Proxy REST API Documentation HTTP://[Alluxio Proxy Hostname]/api/v1 The Alluxio Proxy acts as a REST gateway for clients to communicate with the Alluxio system. There are three different endpoints: 1. The Proxy endpoint gives general info about the proxy service. 1. The Paths endpoint provides a RESTful gateway to the Alluxio file system for metadata operations. 1. The Streams endpoint provides a RESTful gateway to the Alluxio file system for data operations. # APIs ## /paths/{path}/create-directory ### POST <a id="createDirectory">Create a directory at the given path</a> #### Request **Content-Type: ** application/json ##### Parameters <table border="1"> <tr> <th>Name</th> <th>Located in</th> <th>Required</th> <th>Description</th> <th>Default</th> <th>Schema</th> </tr> <tr> <th>path</th> <td>path</td> <td>yes</td> <td> (**Pattern**: `.*`)</td> <td> - </td> <td>string </td> </tr> </table> #### Response **Content-Type: ** application/json | Status Code | Reason | Response Model | |-------------|-------------|----------------| | default | successful operation | - | ## /paths/{path}/create-file ### POST <a id="createFile">Create a file at the given path, use the id with the streams api</a> #### Request **Content-Type: ** application/json ##### Parameters <table border="1"> <tr> <th>Name</th> <th>Located in</th> <th>Required</th> <th>Description</th> <th>Default</th> <th>Schema</th> </tr> <tr> <th>path</th> <td>path</td> <td>yes</td> <td> (**Pattern**: `.*`)</td> <td> - </td> <td>string </td> </tr> </table> #### Response **Content-Type: ** application/json | Status Code | Reason | Response Model | |-------------|-------------|----------------| | 200 | successful operation | | ## /paths/{path}/delete ### POST <a id="delete">Delete the given path</a> #### Request **Content-Type: ** application/json ##### Parameters <table border="1"> <tr> <th>Name</th> <th>Located in</th> <th>Required</th> <th>Description</th> <th>Default</th> <th>Schema</th> </tr> <tr> <th>path</th> <td>path</td> <td>yes</td> <td> (**Pattern**: `.*`)</td> <td> - </td> <td>string </td> </tr> </table> #### Response **Content-Type: ** application/json | Status Code | Reason | Response Model | |-------------|-------------|----------------| | default | successful operation | - | ## /paths/{path}/download-file ### GET <a id="downloadFile">Download the given file at the path</a> #### Request **Content-Type: ** application/json ##### Parameters <table border="1"> <tr> <th>Name</th> <th>Located in</th> <th>Required</th> <th>Description</th> <th>Default</th> <th>Schema</th> </tr> <tr> <th>path</th> <td>path</td> <td>yes</td> <td> (**Pattern**: `.*`)</td> <td> - </td> <td>string </td> </tr> </table> #### Response **Content-Type: ** application/octet-stream | Status Code | Reason | Response Model | |-------------|-------------|----------------| | 200 | successful operation | <a href="#/definitions/InputStream">InputStream</a>| ## /paths/{path}/exists ### POST <a id="exists">Check if the given path exists</a> #### Request **Content-Type: ** application/json ##### Parameters <table border="1"> <tr> <th>Name</th> <th>Located in</th> <th>Required</th> <th>Description</th> <th>Default</th> <th>Schema</th> </tr> <tr> <th>path</th> <td>path</td> <td>yes</td> <td> (**Pattern**: `.*`)</td> <td> - </td> <td>string </td> </tr> </table> #### Response **Content-Type: ** application/json | Status Code | Reason | Response Model | |-------------|-------------|----------------| | 200 | successful operation | | ## /paths/{path}/free ### POST <a id="free">Free the given path</a> #### Request **Content-Type: ** application/json ##### Parameters <table border="1"> <tr> <th>Name</th> <th>Located in</th> <th>Required</th> <th>Description</th> <th>Default</th> <th>Schema</th> </tr> <tr> <th>path</th> <td>path</td> <td>yes</td> <td> (**Pattern**: `.*`)</td> <td> - </td> <td>string </td> </tr> </table> #### Response **Content-Type: ** application/json | Status Code | Reason | Response Model | |-------------|-------------|----------------| | default | successful operation | - | ## /paths/{path}/get-status ### POST <a id="getStatus">Get the file status of the path</a> #### Request **Content-Type: ** application/json ##### Parameters <table border="1"> <tr> <th>Name</th> <th>Located in</th> <th>Required</th> <th>Description</th> <th>Default</th> <th>Schema</th> </tr> <tr> <th>path</th> <td>path</td> <td>yes</td> <td> (**Pattern**: `.*`)</td> <td> - </td> <td>string </td> </tr> </table> #### Response **Content-Type: ** application/json | Status Code | Reason | Response Model | |-------------|-------------|----------------| | 200 | successful operation | <a href="#/definitions/URIStatus">URIStatus</a>| ## /paths/{path}/list-status ### POST <a id="listStatus">List the URIStatuses of the path&#x27;s children</a> #### Request **Content-Type: ** application/json ##### Parameters <table border="1"> <tr> <th>Name</th> <th>Located in</th> <th>Required</th> <th>Description</th> <th>Default</th> <th>Schema</th> </tr> <tr> <th>path</th> <td>path</td> <td>yes</td> <td> (**Pattern**: `.*`)</td> <td> - </td> <td>string </td> </tr> </table> #### Response **Content-Type: ** application/json | Status Code | Reason | Response Model | |-------------|-------------|----------------| | 200 | successful operation | Array[<a href=""></a>]| ## /paths/{path}/mount ### POST <a id="mount">Mounts the src to the given Alluxio path</a> #### Request **Content-Type: ** application/json ##### Parameters <table border="1"> <tr> <th>Name</th> <th>Located in</th> <th>Required</th> <th>Description</th> <th>Default</th> <th>Schema</th> </tr> <tr> <th>path</th> <td>path</td> <td>yes</td> <td> (**Pattern**: `.*`)</td> <td> - </td> <td>string </td> </tr> <tr> <th>src</th> <td>query</td> <td>no</td> <td></td> <td> - </td> <td>string </td> </tr> </table> #### Response **Content-Type: ** application/json | Status Code | Reason | Response Model | |-------------|-------------|----------------| | default | successful operation | - | ## /paths/{path}/open-file ### POST <a id="openFile">Opens the given path for reading, use the id with the stream api</a> #### Request **Content-Type: ** application/json ##### Parameters <table border="1"> <tr> <th>Name</th> <th>Located in</th> <th>Required</th> <th>Description</th> <th>Default</th> <th>Schema</th> </tr> <tr> <th>path</th> <td>path</td> <td>yes</td> <td> (**Pattern**: `.*`)</td> <td> - </td> <td>string </td> </tr> </table> #### Response **Content-Type: ** application/json | Status Code | Reason | Response Model | |-------------|-------------|----------------| | 200 | successful operation | | ## /paths/{path}/rename ### POST <a id="rename">Rename the src path to the dst path</a> #### Request **Content-Type: ** application/json ##### Parameters <table border="1"> <tr> <th>Name</th> <th>Located in</th> <th>Required</th> <th>Description</th> <th>Default</th> <th>Schema</th> </tr> <tr> <th>path</th> <td>path</td> <td>yes</td> <td> (**Pattern**: `.*`)</td> <td> - </td> <td>string </td> </tr> <tr> <th>dst</th> <td>query</td> <td>no</td> <td></td> <td> - </td> <td>string </td> </tr> </table> #### Response **Content-Type: ** application/json | Status Code | Reason | Response Model | |-------------|-------------|----------------| | default | successful operation | - | ## /paths/{path}/set-attribute ### POST <a id="setAttribute">Update attributes for the path</a> #### Request **Content-Type: ** application/json ##### Parameters <table border="1"> <tr> <th>Name</th> <th>Located in</th> <th>Required</th> <th>Description</th> <th>Default</th> <th>Schema</th> </tr> <tr> <th>path</th> <td>path</td> <td>yes</td> <td> (**Pattern**: `.*`)</td> <td> - </td> <td>string </td> </tr> </table> #### Response **Content-Type: ** application/json | Status Code | Reason | Response Model | |-------------|-------------|----------------| | default | successful operation | - | ## /paths/{path}/unmount ### POST <a id="unmount">Unmount the path, the path must be a mount point</a> #### Request **Content-Type: ** application/json ##### Parameters <table border="1"> <tr> <th>Name</th> <th>Located in</th> <th>Required</th> <th>Description</th> <th>Default</th> <th>Schema</th> </tr> <tr> <th>path</th> <td>path</td> <td>yes</td> <td> (**Pattern**: `.*`)</td> <td> - </td> <td>string </td> </tr> </table> #### Response **Content-Type: ** application/json | Status Code | Reason | Response Model | |-------------|-------------|----------------| | default | successful operation | - | ## /proxy/info ### GET <a id="getInfo">Get general Alluxio Proxy service information</a> #### Request ##### Parameters <table border="1"> <tr> <th>Name</th> <th>Located in</th> <th>Required</th> <th>Description</th> <th>Default</th> <th>Schema</th> </tr> <tr> <th>raw_configuration</th> <td>query</td> <td>no</td> <td></td> <td> - </td> <td>boolean </td> </tr> </table> #### Response **Content-Type: ** application/json | Status Code | Reason | Response Model | |-------------|-------------|----------------| | 200 | successful operation | <a href="#/definitions/AlluxioProxyInfo">AlluxioProxyInfo</a>| ## /streams/{id}/close ### POST <a id="close">Closes the stream associated with the id</a> #### Request **Content-Type: ** application/json ##### Parameters <table border="1"> <tr> <th>Name</th> <th>Located in</th> <th>Required</th> <th>Description</th> <th>Default</th> <th>Schema</th> </tr> <tr> <th>id</th> <td>path</td> <td>yes</td> <td></td> <td> - </td> <td>integer (int32)</td> </tr> </table> #### Response **Content-Type: ** application/json | Status Code | Reason | Response Model | |-------------|-------------|----------------| | default | successful operation | - | ## /streams/{id}/read ### POST <a id="read">Returns the input stream associated with the id</a> #### Request **Content-Type: ** application/json ##### Parameters <table border="1"> <tr> <th>Name</th> <th>Located in</th> <th>Required</th> <th>Description</th> <th>Default</th> <th>Schema</th> </tr> <tr> <th>id</th> <td>path</td> <td>yes</td> <td></td> <td> - </td> <td>integer (int32)</td> </tr> </table> #### Response **Content-Type: ** application/octet-stream | Status Code | Reason | Response Model | |-------------|-------------|----------------| | 200 | successful operation | <a href="#/definitions/InputStream">InputStream</a>| ## /streams/{id}/write ### POST <a id="write">Writes to the given output stream associated with the id</a> #### Request **Content-Type: ** application/octet-stream ##### Parameters <table border="1"> <tr> <th>Name</th> <th>Located in</th> <th>Required</th> <th>Description</th> <th>Default</th> <th>Schema</th> </tr> <tr> <th>id</th> <td>path</td> <td>yes</td> <td></td> <td> - </td> <td>integer (int32)</td> </tr> </table> #### Response **Content-Type: ** application/json | Status Code | Reason | Response Model | |-------------|-------------|----------------| | 200 | successful operation | | # Definitions ## <a name="/definitions/AccessControlList">AccessControlList</a> <table border="1"> <tr> <th>name</th> <th>type</th> <th>required</th> <th>description</th> <th>example</th> </tr> <tr> <td>extendedEntries</td> <td> <a href="#/definitions/ExtendedACLEntries">ExtendedACLEntries</a> </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>owningUser</td> <td> string </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>owningGroup</td> <td> string </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>owningUserActions</td> <td> <a href="#/definitions/AclActions">AclActions</a> </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>owningGroupActions</td> <td> <a href="#/definitions/AclActions">AclActions</a> </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>otherActions</td> <td> <a href="#/definitions/AclActions">AclActions</a> </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>mode</td> <td> integer (int32) </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>entries</td> <td> array[<a href="#/definitions/AclEntry">AclEntry</a>] </td> <td>optional</td> <td>-</td> <td></td> </tr> </table> ## <a name="/definitions/AclActions">AclActions</a> <table border="1"> <tr> <th>name</th> <th>type</th> <th>required</th> <th>description</th> <th>example</th> </tr> <tr> <td>actions</td> <td> array[string] </td> <td>optional</td> <td>-</td> <td></td> </tr> </table> ## <a name="/definitions/AclEntry">AclEntry</a> <table border="1"> <tr> <th>name</th> <th>type</th> <th>required</th> <th>description</th> <th>example</th> </tr> <tr> <td>subject</td> <td> string </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>default</td> <td> boolean </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>actions</td> <td> <a href="#/definitions/AclActions">AclActions</a> </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>type</td> <td> string </td> <td>optional</td> <td>-</td> <td></td> </tr> </table> ## <a name="/definitions/AlluxioProxyInfo">AlluxioProxyInfo</a> <table border="1"> <tr> <th>name</th> <th>type</th> <th>required</th> <th>description</th> <th>example</th> </tr> <tr> <td>startTimeMs</td> <td> integer (int64) </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>uptimeMs</td> <td> integer (int64) </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>version</td> <td> string </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>configuration</td> <td> object </td> <td>optional</td> <td>-</td> <td></td> </tr> </table> ## <a name="/definitions/BlockInfo">BlockInfo</a> <table border="1"> <tr> <th>name</th> <th>type</th> <th>required</th> <th>description</th> <th>example</th> </tr> <tr> <td>blockId</td> <td> integer (int64) </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>locations</td> <td> array[<a href="#/definitions/BlockLocation">BlockLocation</a>] </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>length</td> <td> integer (int64) </td> <td>optional</td> <td>-</td> <td></td> </tr> </table> ## <a name="/definitions/BlockLocation">BlockLocation</a> <table border="1"> <tr> <th>name</th> <th>type</th> <th>required</th> <th>description</th> <th>example</th> </tr> <tr> <td>workerAddress</td> <td> <a href="#/definitions/WorkerNetAddress">WorkerNetAddress</a> </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>tierAlias</td> <td> string </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>mediumType</td> <td> string </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>workerId</td> <td> integer (int64) </td> <td>optional</td> <td>-</td> <td></td> </tr> </table> ## <a name="/definitions/DefaultAccessControlList">DefaultAccessControlList</a> <table border="1"> <tr> <th>name</th> <th>type</th> <th>required</th> <th>description</th> <th>example</th> </tr> <tr> <td>empty</td> <td> boolean </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>entries</td> <td> array[<a href="#/definitions/AclEntry">AclEntry</a>] </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>extendedEntries</td> <td> <a href="#/definitions/ExtendedACLEntries">ExtendedACLEntries</a> </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>owningUser</td> <td> string </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>owningGroup</td> <td> string </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>owningUserActions</td> <td> <a href="#/definitions/AclActions">AclActions</a> </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>owningGroupActions</td> <td> <a href="#/definitions/AclActions">AclActions</a> </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>otherActions</td> <td> <a href="#/definitions/AclActions">AclActions</a> </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>mode</td> <td> integer (int32) </td> <td>optional</td> <td>-</td> <td></td> </tr> </table> ## <a name="/definitions/ExtendedACLEntries">ExtendedACLEntries</a> <table border="1"> <tr> <th>name</th> <th>type</th> <th>required</th> <th>description</th> <th>example</th> </tr> <tr> <td>namedGroupActions</td> <td> object </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>namedUserActions</td> <td> object </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>mask</td> <td> <a href="#/definitions/AclActions">AclActions</a> </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>entries</td> <td> array[<a href="#/definitions/AclEntry">AclEntry</a>] </td> <td>optional</td> <td>-</td> <td></td> </tr> </table> ## <a name="/definitions/FileBlockInfo">FileBlockInfo</a> <table border="1"> <tr> <th>name</th> <th>type</th> <th>required</th> <th>description</th> <th>example</th> </tr> <tr> <td>blockInfo</td> <td> <a href="#/definitions/BlockInfo">BlockInfo</a> </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>ufsLocations</td> <td> array[string] </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>offset</td> <td> integer (int64) </td> <td>optional</td> <td>-</td> <td></td> </tr> </table> ## <a name="/definitions/InputStream">InputStream</a> <table border="1"> <tr> <th>name</th> <th>type</th> <th>required</th> <th>description</th> <th>example</th> </tr> </table> ## <a name="/definitions/LocalityTier">LocalityTier</a> <table border="1"> <tr> <th>name</th> <th>type</th> <th>required</th> <th>description</th> <th>example</th> </tr> <tr> <td>tierName</td> <td> string </td> <td>optional</td> <td>Name of the tier</td> <td>host</td> </tr> <tr> <td>value</td> <td> string </td> <td>optional</td> <td>Value of the tier name</td> <td>localhost</td> </tr> </table> ## <a name="/definitions/TieredIdentity">TieredIdentity</a> <table border="1"> <tr> <th>name</th> <th>type</th> <th>required</th> <th>description</th> <th>example</th> </tr> <tr> <td>tiers</td> <td> array[<a href="#/definitions/LocalityTier">LocalityTier</a>] </td> <td>optional</td> <td>Tiers included in the tier identity</td> <td></td> </tr> </table> ## <a name="/definitions/URIStatus">URIStatus</a> <table border="1"> <tr> <th>name</th> <th>type</th> <th>required</th> <th>description</th> <th>example</th> </tr> <tr> <td>inMemoryPercentage</td> <td> integer (int32) </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>inAlluxioPercentage</td> <td> integer (int32) </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>lastModificationTimeMs</td> <td> integer (int64) </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>persistenceState</td> <td> string </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>ttlAction</td> <td> string </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>ufsPath</td> <td> string </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>completed</td> <td> boolean </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>persisted</td> <td> boolean </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>pinned</td> <td> boolean </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>pinnedMediumTypes</td> <td> array[string] </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>mountPoint</td> <td> boolean </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>mountId</td> <td> integer (int64) </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>fileBlockInfos</td> <td> array[<a href="#/definitions/FileBlockInfo">FileBlockInfo</a>] </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>ufsFingerprint</td> <td> string </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>acl</td> <td> <a href="#/definitions/AccessControlList">AccessControlList</a> </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>defaultAcl</td> <td> <a href="#/definitions/DefaultAccessControlList">DefaultAccessControlList</a> </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>ttl</td> <td> integer (int64) </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>replicationMax</td> <td> integer (int32) </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>replicationMin</td> <td> integer (int32) </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>creationTimeMs</td> <td> integer (int64) </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>blockIds</td> <td> array[integer] </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>blockSizeBytes</td> <td> integer (int64) </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>fileId</td> <td> integer (int64) </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>cacheable</td> <td> boolean </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>mode</td> <td> integer (int32) </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>owner</td> <td> string </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>group</td> <td> string </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>folder</td> <td> boolean </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>length</td> <td> integer (int64) </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>name</td> <td> string </td> <td>optional</td> <td>-</td> <td></td> </tr> <tr> <td>path</td> <td> string </td> <td>optional</td> <td>-</td> <td></td> </tr> </table> ## <a name="/definitions/WorkerNetAddress">WorkerNetAddress</a> <table border="1"> <tr> <th>name</th> <th>type</th> <th>required</th> <th>description</th> <th>example</th> </tr> <tr> <td>rpcPort</td> <td> integer (int32) </td> <td>optional</td> <td>Port of the worker's Rpc server for metadata operations</td> <td></td> </tr> <tr> <td>dataPort</td> <td> integer (int32) </td> <td>optional</td> <td>Port of the worker's server for data operations</td> <td></td> </tr> <tr> <td>webPort</td> <td> integer (int32) </td> <td>optional</td> <td>Port which exposes the worker's web UI</td> <td></td> </tr> <tr> <td>domainSocketPath</td> <td> string </td> <td>optional</td> <td>The domain socket path used by the worker, disabled if empty</td> <td></td> </tr> <tr> <td>tieredIdentity</td> <td> <a href="#/definitions/TieredIdentity">TieredIdentity</a> </td> <td>optional</td> <td>The worker's tier identity</td> <td></td> </tr> <tr> <td>host</td> <td> string </td> <td>optional</td> <td>Host name of the worker</td> <td></td> </tr> </table>