WebHDFS REST API
Document Conventions
| Monospaced | Used for commands, HTTP request and responses and code blocks. |
| <Monospaced> | User entered values. |
| [Monospaced] | Optional values. When the value is not specified, the default value is used. |
| Italics | Important phrases and words. |
Introduction
The HTTP REST API supports the complete FileSystem interface for HDFS. The operations and the corresponding FileSystem methods are shown in the next section. The Section HTTP Query Parameter Dictionary specifies the parameter details such as the defaults and the valid values.
Operations
- HTTP GET
- OPEN (see FileSystem.open)
- GETFILESTATUS (see FileSystem.getFileStatus)
- LISTSTATUS (see FileSystem.listStatus)
- GETCONTENTSUMMARY (see FileSystem.getContentSummary)
- GETFILECHECKSUM (see FileSystem.getFileChecksum)
- GETHOMEDIRECTORY (see FileSystem.getHomeDirectory)
- GETDELEGATIONTOKEN (see FileSystem.getDelegationToken)
- HTTP PUT
- CREATE (see FileSystem.create)
- MKDIRS (see FileSystem.mkdirs)
- RENAME (see FileSystem.rename)
- SETREPLICATION (see FileSystem.setReplication)
- SETOWNER (see FileSystem.setOwner)
- SETPERMISSION (see FileSystem.setPermission)
- SETTIMES (see FileSystem.setTimes)
- RENEWDELEGATIONTOKEN (see DistributedFileSystem.renewDelegationToken)
- CANCELDELEGATIONTOKEN (see DistributedFileSystem.cancelDelegationToken)
- HTTP POST
- APPEND (see FileSystem.append)
- HTTP DELETE
- DELETE (see FileSystem.delete)
FileSystem URIs vs HTTP URLs
The FileSystem scheme of WebHDFS is "webhdfs://". A WebHDFS FileSystem URI has the following format.
webhdfs://<HOST>:<HTTP_PORT>/<PATH>
The above WebHDFS URI corresponds to the below HDFS URI.
hdfs://<HOST>:<RPC_PORT>/<PATH>
In the REST API, the prefix "/webhdfs/v1" is inserted in the path and a query is appended at the end. Therefore, the corresponding HTTP URL has the following format.
http://<HOST>:<HTTP_PORT>/webhdfs/v1/<PATH>?op=...
HDFS Configuration Options
Below are the HDFS configuration options for WebHDFS.
| Property Name | Description |
|---|---|
| dfs.webhdfs.enabled | Enable/disable WebHDFS in Namenodes and Datanodes |
| dfs.web.authentication.kerberos.principal | The HTTP Kerberos principal used by Hadoop-Auth in the HTTP endpoint. The HTTP Kerberos principal MUST start with 'HTTP/' per Kerberos HTTP SPENGO specification. |
| dfs.web.authentication.kerberos.keytab | The Kerberos keytab file with the credentials for the HTTP Kerberos principal used by Hadoop-Auth in the HTTP endpoint. |
Authentication
When security is off, the authenticated user is the username specified in the user.name query parameter. If the user.name parameter is not set, the server may either set the authenticated user to a default web user, if there is any, or return an error response.
When security is on, authentication is performed by either Hadoop delegation token or Kerberos SPNEGO. If a token is set in the delegation query parameter, the authenticated user is the user encoded in the token. If the delegation parameter is not set, the user is authenticated by Kerberos SPNEGO.
Below are examples using the curl command tool.
-
Authentication when security is off:
curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?[user.name=<USER>&]op=..."
-
Authentication using Kerberos SPNEGO when security is on:
curl -i --negotiate -u : "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=..."
-
Authentication using Hadoop delegation token when security is on:
curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?delegation=<TOKEN>&op=..."
Proxy Users
When the proxy user feature is enabled, a proxy user P may submit a request on behalf of another user U. The username of U must be specified in the doas query parameter unless a delegation token is presented in authentication. In such case, the information of both users P and U must be encoded in the delegation token.
-
A proxy request when security is off:
curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?[user.name=<USER>&]doas=<USER>&op=..."
-
A proxy request using Kerberos SPNEGO when security is on:
curl -i --negotiate -u : "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?doas=<USER>&op=..."
-
A proxy request using Hadoop delegation token when security is on:
curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?delegation=<TOKEN>&op=..."
File and Directory Operations
Create and Write to a File
- Step 1: Submit a HTTP PUT request without automatically following redirects and without sending the file data.
curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=CREATE [&overwrite=<true|false>][&blocksize=<LONG>][&replication=<SHORT>] [&permission=<OCTAL>][&buffersize=<INT>]"
The request is redirected to a datanode where the file data is to be written:HTTP/1.1 307 TEMPORARY_REDIRECT Location: http://<DATANODE>:<PORT>/webhdfs/v1/<PATH>?op=CREATE... Content-Length: 0
- Step 2: Submit another HTTP PUT request using the URL in the Location header with the file data to be written.
curl -i -X PUT -T <LOCAL_FILE> "http://<DATANODE>:<PORT>/webhdfs/v1/<PATH>?op=CREATE..."
The client receives a 201 Created response with zero content length and the WebHDFS URI of the file in the Location header:HTTP/1.1 201 Created Location: webhdfs://<HOST>:<PORT>/<PATH> Content-Length: 0
Note that the reason of having two-step create/append is for preventing clients to send out data before the redirect. This issue is addressed by the "Expect: 100-continue" header in HTTP/1.1; see RFC 2616, Section 8.2.3. Unfortunately, there are software library bugs (e.g. Jetty 6 HTTP server and Java 6 HTTP client), which do not correctly implement "Expect: 100-continue". The two-step create/append is a temporary workaround for the software library bugs.
See also: overwrite, blocksize, replication, permission, buffersize, FileSystem.create
Append to a File
- Step 1: Submit a HTTP POST request without automatically following redirects and without sending the file data.
curl -i -X POST "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=APPEND[&buffersize=<INT>]"
The request is redirected to a datanode where the file data is to be appended:HTTP/1.1 307 TEMPORARY_REDIRECT Location: http://<DATANODE>:<PORT>/webhdfs/v1/<PATH>?op=APPEND... Content-Length: 0
- Step 2: Submit another HTTP POST request using the URL in the Location header with the file data to be appended.
curl -i -X POST -T <LOCAL_FILE> "http://<DATANODE>:<PORT>/webhdfs/v1/<PATH>?op=APPEND..."
The client receives a response with zero content length:HTTP/1.1 200 OK Content-Length: 0
See the note in the previous section for the description of why this operation requires two steps.
See also: buffersize, FileSystem.append
Open and Read a File
- Submit a HTTP GET request with automatically following redirects.
curl -i -L "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=OPEN [&offset=<LONG>][&length=<LONG>][&buffersize=<INT>]"
The request is redirected to a datanode where the file data can be read:HTTP/1.1 307 TEMPORARY_REDIRECT Location: http://<DATANODE>:<PORT>/webhdfs/v1/<PATH>?op=OPEN... Content-Length: 0
The client follows the redirect to the datanode and receives the file data:HTTP/1.1 200 OK Content-Type: application/octet-stream Content-Length: 22 Hello, webhdfs user!
See also: offset, length, buffersize, FileSystem.open
Make a Directory
- Submit a HTTP PUT request.
curl -i -X PUT "http://<HOST>:<PORT>/<PATH>?op=MKDIRS[&permission=<OCTAL>]"
The client receives a response with a boolean JSON object:HTTP/1.1 200 OK Content-Type: application/json Transfer-Encoding: chunked {"boolean": true}
See also: permission, FileSystem.mkdirs
Rename a File/Directory
- Submit a HTTP PUT request.
curl -i -X PUT "<HOST>:<PORT>/webhdfs/v1/<PATH>?op=RENAME&destination=<PATH>"
The client receives a response with a boolean JSON object:HTTP/1.1 200 OK Content-Type: application/json Transfer-Encoding: chunked {"boolean": true}
See also: destination, FileSystem.rename
Delete a File/Directory
- Submit a HTTP DELETE request.
curl -i -X DELETE "http://<host>:<port>/webhdfs/v1/<path>?op=DELETE [&recursive=<true|false>]"
The client receives a response with a boolean JSON object:HTTP/1.1 200 OK Content-Type: application/json Transfer-Encoding: chunked {"boolean": true}
See also: recursive, FileSystem.delete
Status of a File/Directory
- Submit a HTTP GET request.
curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=GETFILESTATUS"
The client receives a response with a FileStatus JSON object:HTTP/1.1 200 OK Content-Type: application/json Transfer-Encoding: chunked { "FileStatus": { "accessTime" : 0, "blockSize" : 0, "group" : "supergroup", "length" : 0, //in bytes, zero for directories "modificationTime":<PHONE_NUMBER>227, "owner" : "webuser", "pathSuffix" : "", "permission" : "777", "replication" : 0, "type" : "DIRECTORY" //enum {FILE, DIRECTORY} } }
See also: FileSystem.getFileStatus
List a Directory
- Submit a HTTP GET request.
curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=LISTSTATUS"
The client receives a response with a FileStatuses JSON object:HTTP/1.1 200 OK Content-Type: application/json Content-Length: 427 { "FileStatuses": { "FileStatus": [ { "accessTime" :<PHONE_NUMBER>771, "blockSize" : 33554432, "group" : "supergroup", "length" : 24930, "modificationTime":<PHONE_NUMBER>771, "owner" : "webuser", "pathSuffix" : "a.patch", "permission" : "644", "replication" : 1, "type" : "FILE" }, { "accessTime" : 0, "blockSize" : 0, "group" : "supergroup", "length" : 0, "modificationTime":<PHONE_NUMBER>256, "owner" : "szetszwo", "pathSuffix" : "bar", "permission" : "711", "replication" : 0, "type" : "DIRECTORY" }, ... ] } }
See also: FileSystem.listStatus
Other File System Operations
Get Content Summary of a Directory
- Submit a HTTP GET request.
curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=GETCONTENTSUMMARY"
The client receives a response with a ContentSummary JSON object:HTTP/1.1 200 OK Content-Type: application/json Transfer-Encoding: chunked { "ContentSummary": { "directoryCount": 2, "fileCount" : 1, "length" : 24930, "quota" : -1, "spaceConsumed" : 24930, "spaceQuota" : -1 } }
See also: FileSystem.getContentSummary
Get File Checksum
- Submit a HTTP GET request.
curl -i "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=GETFILECHECKSUM"
The request is redirected to a datanode:HTTP/1.1 307 TEMPORARY_REDIRECT Location: http://<DATANODE>:<PORT>/webhdfs/v1/<PATH>?op=GETFILECHECKSUM... Content-Length: 0
The client follows the redirect to the datanode and receives a FileChecksum JSON object:HTTP/1.1 200 OK Content-Type: application/json Transfer-Encoding: chunked { "FileChecksum": { "algorithm": "MD5-of-1MD5-of-512CRC32", "bytes" : "eadb10de24aa315748930df6e185c0d ...", "length" : 28 } }
See also: FileSystem.getFileChecksum
Get Home Directory
- Submit a HTTP GET request.
curl -i "http://<HOST>:<PORT>/webhdfs/v1/?op=GETHOMEDIRECTORY"
The client receives a response with a Path JSON object:HTTP/1.1 200 OK Content-Type: application/json Transfer-Encoding: chunked {"Path": "/user/szetszwo"}
See also: FileSystem.getHomeDirectory
Set Permission
- Submit a HTTP PUT request.
curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=SETPERMISSION [&permission=<OCTAL>]"
The client receives a response with zero content length:HTTP/1.1 200 OK Content-Length: 0
See also: permission, FileSystem.setPermission
Set Owner
- Submit a HTTP PUT request.
curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=SETOWNER [&owner=<USER>][&group=<GROUP>]"
The client receives a response with zero content length:HTTP/1.1 200 OK Content-Length: 0
See also: owner, group, FileSystem.setOwner
Set Replication Factor
- Submit a HTTP PUT request.
curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=SETREPLICATION [&replication=<SHORT>]"
The client receives a response with a boolean JSON object:HTTP/1.1 200 OK Content-Type: application/json Transfer-Encoding: chunked {"boolean": true}
See also: replication, FileSystem.setReplication
Set Access or Modification Time
- Submit a HTTP PUT request.
curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/<PATH>?op=SETTIMES [&modificationtime=<TIME>][&accesstime=<TIME>]"
The client receives a response with zero content length:HTTP/1.1 200 OK Content-Length: 0
See also: modificationtime, accesstime, FileSystem.setTimes
Delegation Token Operations
Get Delegation Token
- Submit a HTTP GET request.
curl -i "http://<HOST>:<PORT>/webhdfs/v1/?op=GETDELEGATIONTOKEN&renewer=<USER>"
The client receives a response with a Token JSON object:HTTP/1.1 200 OK Content-Type: application/json Transfer-Encoding: chunked { "Token": { "urlString": "JQAIaG9y..." } }
See also: renewer, FileSystem.getDelegationToken
Renew Delegation Token
- Submit a HTTP PUT request.
curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/?op=RENEWDELEGATIONTOKEN&token=<TOKEN>"
The client receives a response with a long JSON object:HTTP/1.1 200 OK Content-Type: application/json Transfer-Encoding: chunked {"long":<PHONE_NUMBER>997} //the new expiration time
See also: token, DistributedFileSystem.renewDelegationToken
Cancel Delegation Token
- Submit a HTTP PUT request.
curl -i -X PUT "http://<HOST>:<PORT>/webhdfs/v1/?op=CANCELDELEGATIONTOKEN&token=<TOKEN>"
The client receives a response with zero content length:HTTP/1.1 200 OK Content-Length: 0
See also: token, DistributedFileSystem.cancelDelegationToken
Error Responses
When an operation fails, the server may throw an exception. The JSON schema of error responses is defined in RemoteException JSON schema. The table below shows the mapping from exceptions to HTTP response codes.
HTTP Response Codes
| Exceptions | HTTP Response Codes |
|---|---|
| IllegalArgumentException | 400 Bad Request |
| UnsupportedOperationException | 400 Bad Request |
| SecurityException | 401 Unauthorized |
| IOException | 403 Forbidden |
| FileNotFoundException | 404 Not Found |
| RumtimeException | 500 Internal Server Error |
Below are examples of exception responses.
Illegal Argument Exception
HTTP/1.1 400 Bad Request Content-Type: application/json Transfer-Encoding: chunked { "RemoteException": { "exception" : "IllegalArgumentException", "javaClassName": "java.lang.IllegalArgumentException", "message" : "Invalid value for webhdfs parameter \"permission\": ..." } }
Security Exception
HTTP/1.1 401 Unauthorized Content-Type: application/json Transfer-Encoding: chunked { "RemoteException": { "exception" : "SecurityException", "javaClassName": "java.lang.SecurityException", "message" : "Failed to obtain user group information: ..." } }
Access Control Exception
HTTP/1.1 403 Forbidden Content-Type: application/json Transfer-Encoding: chunked { "RemoteException": { "exception" : "AccessControlException", "javaClassName": "org.apache.hadoop.security.AccessControlException", "message" : "Permission denied: ..." } }
File Not Found Exception
HTTP/1.1 404 Not Found Content-Type: application/json Transfer-Encoding: chunked { "RemoteException": { "exception" : "FileNotFoundException", "javaClassName": "java.io.FileNotFoundException", "message" : "File does not exist: /foo/a.patch" } }
JSON Schemas
All operations, except for OPEN, either return a zero-length response or a JSON response . For OPEN, the response is an octet-stream. The JSON schemas are shown below. See draft-zyp-json-schema-03 for the syntax definitions of the JSON schemas.
Boolean JSON Schema
{ "name" : "boolean", "properties": { "boolean": { "description": "A boolean value", "type" : "boolean", "required" : true } } }
See also: MKDIRS, RENAME, DELETE, SETREPLICATION
ContentSummary JSON Schema
{ "name" : "ContentSummary", "properties": { "ContentSummary": { "type" : "object", "properties": { "directoryCount": { "description": "The number of directories.", "type" : "integer", "required" : true }, "fileCount": { "description": "The number of files.", "type" : "integer", "required" : true }, "length": { "description": "The number of bytes used by the content.", "type" : "integer", "required" : true }, "quota": { "description": "The namespace quota of this directory.", "type" : "integer", "required" : true }, "spaceConsumed": { "description": "The disk space consumed by the content.", "type" : "integer", "required" : true }, "spaceQuota": { "description": "The disk space quota.", "type" : "integer", "required" : true } } } } }
See also: GETCONTENTSUMMARY
FileChecksum JSON Schema
{ "name" : "FileChecksum", "properties": { "FileChecksum": { "type" : "object", "properties": { "algorithm": { "description": "The name of the checksum algorithm.", "type" : "string", "required" : true }, "bytes": { "description": "The byte sequence of the checksum in hexadecimal.", "type" : "string", "required" : true }, "length": { "description": "The length of the bytes (not the length of the string).", "type" : "integer", "required" : true } } } } }
See also: GETFILECHECKSUM
FileStatus JSON Schema
{ "name" : "FileStatus", "properties": { "FileStatus": fileStatusProperties //See FileStatus Properties } }
See also: GETFILESTATUS, FileStatus
FileStatus Properties
JavaScript syntax is used to define fileStatusProperties so that it can be referred in both FileStatus and FileStatuses JSON schemas.
var fileStatusProperties = { "type" : "object", "properties": { "accessTime": { "description": "The access time.", "type" : "integer", "required" : true }, "blockSize": { "description": "The block size of a file.", "type" : "integer", "required" : true }, "group": { "description": "The group owner.", "type" : "string", "required" : true }, "length": { "description": "The number of bytes in a file.", "type" : "integer", "required" : true }, "modificationTime": { "description": "The modification time.", "type" : "integer", "required" : true }, "owner": { "description": "The user who is the owner.", "type" : "string", "required" : true }, "pathSuffix": { "description": "The path suffix.", "type" : "string", "required" : true }, "permission": { "description": "The permission represented as a octal string.", "type" : "string", "required" : true }, "replication": { "description": "The number of replication of a file.", "type" : "integer", "required" : true }, "type": { "description": "The type of the path object.", "enum" : ["FILE", "DIRECTORY"], "required" : true } } };
FileStatuses JSON Schema
A FileStatuses JSON object represents an array of FileStatus JSON objects.
{ "name" : "FileStatuses", "properties": { "FileStatuses": { "type" : "object", "properties": { "FileStatus": { "description": "An array of FileStatus", "type" : "array", "items" : fileStatusProperties //See FileStatus Properties } } } } }
See also: LISTSTATUS, FileStatus
Long JSON Schema
{ "name" : "long", "properties": { "long": { "description": "A long integer value", "type" : "integer", "required" : true } } }
See also: RENEWDELEGATIONTOKEN,
Path JSON Schema
{ "name" : "Path", "properties": { "Path": { "description": "The string representation a Path.", "type" : "string", "required" : true } } }
See also: GETHOMEDIRECTORY, Path
RemoteException JSON Schema
{ "name" : "RemoteException", "properties": { "RemoteException": { "type" : "object", "properties": { "exception": { "description": "Name of the exception", "type" : "string", "required" : true }, "message": { "description": "Exception message", "type" : "string", "required" : true }, "javaClassName": //an optional property { "description": "Java class name of the exception", "type" : "string", } } } } }
Token JSON Schema
{ "name" : "Token", "properties": { "Token": { "type" : "object", "properties": { "urlString": { "description": "A delegation token encoded as a URL safe string.", "type" : "string", "required" : true } } } } }
See also: GETDELEGATIONTOKEN, the note in Delegation.
HTTP Query Parameter Dictionary
Access Time
| Name | accesstime |
| Description | The access time of a file/directory. |
| Type | long |
| Default Value | -1 (means keeping it unchanged) |
| Valid Values | -1 or a timestamp |
| Syntax | Any integer. |
See also: SETTIMES
Block Size
| Name | blocksize |
| Description | The block size of a file. |
| Type | long |
| Default Value | Specified in the configuration. |
| Valid Values | > 0 |
| Syntax | Any integer. |
See also: CREATE
Buffer Size
| Name | buffersize |
| Description | The size of the buffer used in transferring data. |
| Type | int |
| Default Value | Specified in the configuration. |
| Valid Values | > 0 |
| Syntax | Any integer. |
See also: CREATE, APPEND, OPEN
Delegation
| Name | delegation |
| Description | The delegation token used for authentication. |
| Type | String |
| Default Value | <empty> |
| Valid Values | An encoded token. |
| Syntax | See the note below. |
Note that delegation tokens are encoded as a URL safe string; see encodeToUrlString() and decodeFromUrlString(String) in org.apache.hadoop.security.token.Token for the details of the encoding.
See also: Authentication
Destination
| Name | destination |
| Description | The destination path used in RENAME. |
| Type | Path |
| Default Value | <empty> (an invalid path) |
| Valid Values | An absolute FileSystem path without scheme and authority. |
| Syntax | Any path. |
See also: RENAME
Do As
| Name | doas |
| Description | Allowing a proxy user to do as another user. |
| Type | String |
| Default Value | null |
| Valid Values | Any valid username. |
| Syntax | Any string. |
See also: Proxy Users
Group
| Name | group |
| Description | The name of a group. |
| Type | String |
| Default Value | <empty> (means keeping it unchanged) |
| Valid Values | Any valid group name. |
| Syntax | Any string. |
See also: SETOWNER
Length
| Name | length |
| Description | The number of bytes to be processed. |
| Type | long |
| Default Value | null (means the entire file) |
| Valid Values | >= 0 or null |
| Syntax | Any integer. |
See also: OPEN
Modification Time
| Name | modificationtime |
| Description | The modification time of a file/directory. |
| Type | long |
| Default Value | -1 (means keeping it unchanged) |
| Valid Values | -1 or a timestamp |
| Syntax | Any integer. |
See also: SETTIMES
Offset
| Name | offset |
| Description | The starting byte position. |
| Type | long |
| Default Value | 0 |
| Valid Values | >= 0 |
| Syntax | Any integer. |
See also: OPEN
Op
| Name | op |
| Description | The name of the operation to be executed. |
| Type | enum |
| Default Value | null (an invalid value) |
| Valid Values | Any valid operation name. |
| Syntax | Any string. |
See also: Operations
Overwrite
| Name | overwrite |
| Description | If a file already exists, should it be overwritten? |
| Type | boolean |
| Default Value | false |
| Valid Values | true | false |
| Syntax | true | false |
See also: CREATE
Owner
| Name | owner |
| Description | The username who is the owner of a file/directory. |
| Type | String |
| Default Value | <empty> (means keeping it unchanged) |
| Valid Values | Any valid username. |
| Syntax | Any string. |
See also: SETOWNER
Permission
| Name | permission |
| Description | The permission of a file/directory. |
| Type | Octal |
| Default Value | 755 |
| Valid Values | 0 - 777 |
| Syntax | Any radix-8 integer (leading zeros may be omitted.) |
See also: CREATE, MKDIRS, SETPERMISSION
Recursive
| Name | recursive |
| Description | Should the operation act on the content in the subdirectories? |
| Type | boolean |
| Default Value | false |
| Valid Values | true | false |
| Syntax | true | false |
See also: RENAME
Renewer
| Name | renewer |
| Description | The username of the renewer of a delegation token. |
| Type | String |
| Default Value | <empty> (means the current user) |
| Valid Values | Any valid username. |
| Syntax | Any string. |
See also: GETDELEGATIONTOKEN
Replication
| Name | replication |
| Description | The number of replications of a file. |
| Type | short |
| Default Value | Specified in the configuration. |
| Valid Values | > 0 |
| Syntax | Any integer. |
See also: CREATE, SETREPLICATION
Token
| Name | token |
| Description | The delegation token used for the operation. |
| Type | String |
| Default Value | <empty> |
| Valid Values | An encoded token. |
| Syntax | See the note in Delegation. |
See also: RENEWDELEGATIONTOKEN, CANCELDELEGATIONTOKEN
Username
| Name | user.name |
| Description | The authenticated user; see Authentication. |
| Type | String |
| Default Value | null |
| Valid Values | Any valid username. |
| Syntax | Any string. |
See also: Authentication


Static Application Bundles¶
Application developers can choose to include their P2UX application bundle as a static resource contained in their native application binary. Providing the application bundle as a static resource removes the need for connectivity when the application runs for the first time.
Potential issues to consider with this approach are:
- If dynamic updates are NOT allowed, updates to application bundle have to be made by updating the application binary itself to include the updated bundle. This means resubmitting your application to the respective stores which can take time to get approval.
- If dynamic updates are allowed, a new installation of the application may end up updating its content immediately on first install as the embedded application bundle may be out of date.
Important
Currently Builder doesn't provide a direct mechanism to download the bundle for inclusion in a native application. The Coordinator product does provide a way to use application bundles. As of this writting, that application has not been released for public use. Check back soon for more information, or contact P2UX support.
The following example sets up an application that supports both Phone and Tablet form factors to use embedded resources. The resources have been unzipped into subdirectories in the project named phone
and tablet
to hold the different resources.
Note
If your project resources are exactly the same for phone and tablet form factors, you can setup the resource usage to point to the same subdirectory in your project. Otherwise they should be in their own subdirectories.
iOS/tvOS¶
Objective-C¶
In AppDelegate.m
:
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { NSString* appKey = @"xxxxx"; // Define the resources for both Phone and Tablet // for this case, both are using static resources in sub directories named // "phone" and "tablet" NSArray* resources = @[ @{P2UXApp_PackageAttrib_FormFactor:@0, // Phone P2UXApp_PackageAttrib_Update:P2UXApp_PackageUpdate_Auto, P2UXApp_PackageAttrib_Type:P2UXApp_PackageType_Static, P2UXApp_PackageAttrib_Package:@"phone"}, @{P2UXApp_PackageAttrib_FormFactor:@1, // Tablet P2UXApp_PackageAttrib_Update:P2UXApp_PackageUpdate_Auto, P2UXApp_PackageAttrib_Type:P2UXApp_PackageType_Static, P2UXApp_PackageAttrib_Package:@"tablet"} ]; NSDictionary* opts; // For Debug builds, use the Stage Environment. That way we can test things before // release #ifdef DEBUG opts = @{P2UXAppCreator_Opt_Env: P2UXAppCreator_Opt_Env_Stage}; #endif [P2UXAppCreator createApplicationWithKey:appKey opts:opts resources:resources delegate:self]; return [super application:application didFinishLaunchingWithOptions:launchOptions]; }
Swift¶
In AppDelegate.swift
:
... func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool { let appKey = "xxxxx"; // Define the resources for both Phone and Tablet // for this case, both are using static resources in sub directories named // "phone" and "tablet" let resources = [ [P2UXApp_PackageAttrib_FormFactor:0, // Phone P2UXApp_PackageAttrib_Update:P2UXApp_PackageUpdate_Auto, P2UXApp_PackageAttrib_Type:P2UXApp_PackageType_Static, P2UXApp_PackageAttrib_Package:"phone"], [P2UXApp_PackageAttrib_FormFactor:1, // Tablet P2UXApp_PackageAttrib_Update:P2UXApp_PackageUpdate_Auto, P2UXApp_PackageAttrib_Type:P2UXApp_PackageType_Static, P2UXApp_PackageAttrib_Package:"tablet"] ] var opts : [AnyHashable : Any]; // For Debug builds, use the Stage Environment. That way we can test things before // release #if DEBUG opts = [ P2UXAppCreator_Opt_Env: P2UXAppCreator_Opt_Env_Stage ] #endif P2UXAppCreator.createApplication(withKey: appKey, opts: opts, resources: resources, delegate: self) return true } ...
Android¶
In MainActivity.java
:
public class MainActivity extends P2UXAppFragmentActivity { @Override public void onCreate(Bundle savedInstanceState) { mAppKey = "0006.6ad72f39bc0b6181f522b51595e0280d2c1505bd7862c702d500744ae4d705fd"; if (savedInstanceState == null) { savedInstanceState = new Bundle(); } // Define the resources for both Phone and Tablet // for this case, both are using static resources in sub directories named // "phone" and "tablet" ArrayList<HashMap<String, Object>> resources = new ArrayList<>(); // Phone form factor HashMap<String, Object> formFactor = new HashMap<>(); formFactor.put(P2UXAppTypes.P2UXApp_PackageAttrib_FormFactor, 0); formFactor.put(P2UXAppTypes.P2UXApp_PackageAttrib_Type, P2UXAppTypes.P2UXApp_PackageType_Static); formFactor.put(P2UXAppTypes.P2UXApp_PackageAttrib_Package, "phone"); formFactor.put(P2UXAppTypes.P2UXApp_PackageAttrib_Update, P2UXAppTypes.P2UXApp_PackageUpdate_Auto); resources.add(formFactor); // Tablet form factor formFactor = new HashMap<>(); formFactor.put(P2UXAppTypes.P2UXApp_PackageAttrib_FormFactor, 1); formFactor.put(P2UXAppTypes.P2UXApp_PackageAttrib_Type, P2UXAppTypes.P2UXApp_PackageType_Static); formFactor.put(P2UXAppTypes.P2UXApp_PackageAttrib_Package, "tablet"); formFactor.put(P2UXAppTypes.P2UXApp_PackageAttrib_Update, P2UXAppTypes.P2UXApp_PackageUpdate_Auto); resources.add(formFactor); setResources(resources); // Setup options savedInstanceState.putString(P2UXAppCreator.P2UXAppCreator_Opt_Env, P2UXAppCreator.P2UXAppCreator_Opt_Env_Recent); // Setup where data sources are persisted to savedInstanceState.putString(P2UXAppCreator.P2UXAppCreator_Opt_PersistData, P2UXAppCreator.P2UXAppCreator_Opt_PersistData_Internal); super.onCreate(savedInstanceState); applyTranslucentStatusBar(); } }