APIs for non-multipart file uploads are available in the HTTP interface only.
Origin Storage provides two techniques for non-multipart upload. Use the following table to decide which technique is best for you.
| Technique | Description | End Point | Where to Find Information |
|---|---|---|---|
| Web Browser Upload | Does an HTTP POST upload using multipart form-data. Use this if you want the ability to upload a file from a web page. This technique is relatively slow because the checksum is calculated after the file is at rest. (The API has to open and read the file to calculate the checksum.) A basic working sample page that illustrates the web browser upload capability is available. | /post/file | Web Browser Upload |
| File Raw Post | Uploads a file as a stream. The only payload is the file data. Faster than Web Browser Upload because the file’s checksum is calculated inline. Also no overhead from form mime encoding . | /post/raw | File Raw Post |
For files larger than 10GB, use the multipart upload functionality. See Uploading Files — Multipart for information.
Web Browser Upload
1POST to /post/file
Does an HTTP POST upload using multipart form-data. Slower than File Raw Post.
When the file creation is complete, the system sets the parent directory’s mtime (last modification time) to the current system time.
An end-to-end /post/file upload example is available. See
/post/file Example.Request Headers
| Header Name | Type | Description |
|---|---|---|
| X-Agile-Authorization | str | Valid token from a call to login (JSON-RPC interface) or /account/login (HTTP interface). See Log In Using JSON-RPC and Log in Using the HTTP Interface, respectively. As an alternative, you can instead pass the token as a query string on the URL. See curl Sample Request 2. |
| X-Agile-Content-Type | str | Optional Lets the API look up or detect content type for the file to upload. If this header is not present or the content type provided in it is invalid, the content type will be derived from the Content-Type field of the MIME-encoded attachment. If a suitable mime type is not detected from the mime attachment, the mime type will be derived from the file name’s extension. Must be a valid Origin Storage MIME type (see Content Types). See also Content Type Handling. |
| X-Agile-Content-Detect | str | Optional Instructs the API to detect the content type. The API will ignore this header if you use the X-Agile-Content-Type header. Pass one of: - name: lookup MIME type by using the filename, usually the extension - content: lookup MIME type by scanning the contents of the file - auto: first lookup by name, then by content if no name matchesSee also Content Type Handling. |
| X-Agile-Checksum | str | Optional The hexlified version of the bytes that make up the file’s sha256 checksum. Origin Storage will calculate the file’s checksum and compare it with the value of X-Agile-Checksum. (When a file first arrives at a landing pad, it is placed in a temporary area called a ‘scratch space’. It is at this point that the checksum comparison occurs.)If X-Agile-Checksum is provided and it matches the calculated checksum, the file will be stored and replicated.If X-Agile-Checksum is provided and it does not match the calculated checksum, the file will not be ingested. Instead, error code -26 (invalid checksum) will be returned and the file will be removed from landing pad’s scratch space and will not be ingested. |
| X-Agile-Recursive | str | Optional When uploading a file to the location specified by the directory form field, this header instructs the API to create any leading directories if they do not already exist. If you set the value to true, non-existing leading directories will be created.If you omit the X-Agile-Recursive header or set it to false, then non-existing leading directories will not be created.If you use both this header and the recursive form field and the two are different, the X-Agile-Recursive header will take precedence.Defaults to false. |
Form Fields
| Field Name | Type | Description |
|---|---|---|
| uploadFile | str | Path and name of file to upload. See also About the uploadFile Form Field. |
| basename | str | Optional Name of file as it will be stored in Origin Storage, minus the path. Forward slashes / are not allowed. See also How Uploaded File Paths Are Determined |
| directory | str | Optional Directory in Origin Storage where the file will be stored Defaults to the root directory See also How Uploaded File Paths Are Determined. |
| recursive | str | Optional When uploading a file to the location specified by the directory form field, this field instructs the API to create any leading directories if they do not already exist. If you set the value to true, non-existing leading directories will be created.If you omit the field or set it to false, then non-existing leading directories will not be created.If you use both this field and X-Agile-Recursive header and the two are different, the X-Agile-Recursive header will take precedence.Defaults to false. |
| return_url | str | Optional Provides the ability to set a “custom” url to redirect to. If you include this field you don’t have to include the return_referer field. |
| return_referer | int | Optional Provides ability to redirect to the location in the Referer1 header (if it is present). In this case, Origin Storage sends a 302 redirect to the Referer header location.If you want to redirect to a custom location, omit the return_referer field and include the custom location in the return_url field.The Referer header is sent by web browsers automatically and identifies the address of the webpage that linked to the resource being requested. |
| expose_egress | str | Optional How to expose egress. Valid values: PARTIAL: expose egress immediately (partially uploaded content can be served). COMPLETE: (default) expose egress when the file completes uploading. POLICY: expose when the file is in policy. Defaults to COMPLETE |
| mtime | int | Optional File modification time in seconds since epoch. Defaults to 0 — current timestamp. |
How Uploaded File Paths Are Determined
The complete path of the uploaded object will be the
directory field value + / + basename field value. If the basename value has any forward slashes in it, the last path component will be used and the leading paths will be stripped. For instance, if you pass /test for directory and /1983/img001.jpg for basename, the final path will be /test/img001.jpg (the 1983 is stripped).About the uploadFile Form Field
uploadFile is a multipart/form-data encoded payload as in this example:1------------------------------44f9af2ecd0c2Content-Disposition: form-data; name="uploadFile"; filename="test.txt"3Content-Type: text/plain45Sample data6------------------------------44f9af2ecd0c--
HTTP Response Codes and Request Status Codes
On success the call returns an HTTP 200 status code, and 0 in the
X-Agile-Status header.On error, the HTTP Status Code is an error code, and the error is reflected in the
X-Agile-Status header. The following table provides details about response values.| HTTP Status Code | Description | Possible X-Agile-Status Values |
|---|---|---|
| 200 | Success | 0: success |
| 400 | Bad request, missing or invalid parameters | -3: no parent directory. One or more path segments in the directory form field do not exist and you did not provide a value for the recursive form field or the X-Agile-Recursive request header.-8: invalid path (path too long) in the directory form field -21: invalid value in the expose_egress form field -23: empty file -24: missing upload file in HTTP POST (You did not supply a file to upload.) -25: upload not supported; you attempted to upload more than one file. -26: invalid checksum -27: invalid value in the mtime form field -33: invalid value in the X-Content-Type header -48: invalid value in the X-Content-Detect header |
| 401 | unauthorized, missing X-Agile-Authorization header | -10001: missing X-Agile-Authorization header |
| 403 | Invalid authentication credentials (invalid token) | -10001: Invalid token |
| 500 | Internal server error | -5: Generic error |
| 503 | Service unavailable | -22: disk full |
Response Headers
| Header Name | Type | Description |
|---|---|---|
| X-Agile-Status | int | Contains response codes. (See HTTP Response Codes and Request Status Codes.) |
| X-Agile-Path | str | File name and path where the file was uploaded |
| X-Agile-Size | int | Size in bytes of the file that this call uploaded |
| X-Agile-Checksum | str | File’s SHA-256 hexadecimal digest |
curl Sample Request 1
Upload super test file.txt into the root directory. Also pass a basename.
1curl -v -k\2-H "X-Agile-Authorization: 4f173c74-c929-4f91-9e0e-645a31343258"\3-F "uploadFile=@/super test file.txt"\4-F "basename=super test file.txt"\5-F "directory=/"\6http://{Account name}.upload.llnw.net/post/file
Sample 1 Success Response
1HTTP/1.1 200 OK2Date: Fri, 19 Jun 2015 20:45:01 GMT3Server Apache is not deny listed4Server: Apache5Access-Control-Allow-Origin: *6Access-Control-Allow-Headers: X-Agile-Authorization, X-Content-Type7Access-Control-Allow-Methods: OPTIONS8X-Agile-Status: 09Content-Length: 010X-Agile-Checksum: d995a1c6b9ba371c2273f209d6659253bf457b3fa047ce6c959ca9911X-Agile-Size: 1012X-Agile-Path: /{Account Name}/super test file.txt13Content-Type: text/json;charset=utf-8
curl Sample Request 2
Send the token on the url in a query string. Also pass a basename.
1curl -v -k\2-F "uploadFile=@/super file2.txt"\3-F "basename=super file2.txt"\4-F "directory=/"\5http://{Account name}.upload.llnw.net/post/file?token=4f174-c929-4f91-9e0e-645a31
Sample 2 Success Response
1HTTP/1.1 200 OK2Date: Wed, 05 Aug 2015 15:43:55 GMT3Server Apache is not deny listed4Server: Apache5Access-Control-Allow-Origin: *6Access-Control-Allow-Headers: X-Agile-Authorization, X-Content-Type7Access-Control-Allow-Methods: OPTIONS8X-Agile-Status: 09Content-Length: 010X-Agile-Checksum: d995a1c6b9ba371c2273f6659253bf457b3fa047ce62dd8274ac959ca9911X-Agile-Size: 1012X-Agile-Path: /{Account name}/super file2.txt13Content-Type: text/json;charset=utf-8
File Raw Post
1POST to post/raw
Uploads a file as a stream.
Upload speed is faster than Web Browser Upload.
When the file creation is complete, the system sets the parent directory’s mtime (last modification time) to the current system time.
An end-to-end /post/raw upload example is available. See
/post/raw Example.Request Headers
| Header Name | Type | Description |
|---|---|---|
| X-Agile-Authorization | str | Valid token from a call to login (JSON-RPC interface) or /account/login (HTTP interface). See Log In Using JSON-RPC and Log in Using the HTTP Interface, respectively. |
| X-Agile-Basename | str | Optional Name of file as it will be stored in Origin Storage, minus the path. Forward slashes / not allowed.If you don’t provide a value for X-Agile-Basename, the API will create a file name in the form of post-<UUID4 in hex notation>. Example:post-ddbb5628fdd3433181ba9771f5709190(UUID4 is a random Universally Unique ID.)The file name must not include two consecutive periods. |
| X-Agile-Content-Detect | str | Optional Instructs the API to detect the content type. The API will ignore this header if you use the X-Agile-Content-Type header.Pass one of: - name: lookup MIME type by using the filename, usually the extension - content: lookup MIME type by scanning the contents of the file - auto: first lookup by name, then by content if no name matches. See also Content Type Handling. |
| X-Agile-Content-Type | str | Optional Lets the API look up or detect content type for the file to upload. If this header is not present or the content type provided in it is invalid, the content type will be derived from the Content-Type field of the MIME-encoded attachment. If a suitable mime type is not detected from the mime attachment, the mime type will be derived from the file name’s extension. Must be a valid Origin Storage MIME type (see Content Types). See also Content Type Handling. |
| X-Agile-Directory | str | Optional Directory in Origin Storage where file will be stored. Defaults to the root directory |
| The file name must not include two consecutive periods. | ||
| X-Agile-Encoding | str | Optional The default behavior is to treat paths as US ASCII. If the values for X-Agile-Basename and X-Agile-Directory contain UTF-8 characters, then include this header and set its value to UTF8, which will cause the API to treat values as URI quote paths. Note:-You must quote paths according to URL parameter quoting defined in RFC3986 of the Internet Engineering Task Force. -Characters %20 and + turn into spaces. -Special characters you must handle are: percent sign, dollar sign, ampersand, plus sign, comma, forward slash, colon, semi colon, equal sign, question mark and the @ symbol. See Using UTF-8 Characters in Request Headers. |
| X-Agile-Expose-Egress | str | Optional When to make the file available for egress. Valid values: -PARTIAL: expose egress immediately (partially uploaded content can be served) -COMPLETE: (default) expose egress when the file completes uploading -POLICY: expose when the file is in policy |
| X-Agile-MTime | str | Optional File last modification time in seconds since epoch. Defaults to zero (current time) |
| X-Agile-Recursive | str | Optional. When uploading a file to the location specified by the X-Agile-Directory header, this header instructs the API to create any leading paths if they do not already exist.If you set the value to true, non-existing leading paths will be created. If you omit the X-Agile-Recursive header or set it to false, then non-existing leading paths will not be created and the call will fail.Other values you can pass that are equivalent to true: - yes - 1 Other values you can pass that are equivalent to false: - no - 0 Defaults to false. |
| X-Agile-Checksum | str | Optional The hexlified version of the bytes that make up the file’s sha256 checksum. Origin Storage will calculate the file’s checksum and compare it with the value of X-Agile-Checksum. (When a file first arrives at a landing pad, it is placed in a temporary area called a ‘scratch space’. It is at this point that the checksum comparison occurs.)If X-Agile-Checksum is provided and it matches the calculated checksum, the file will be stored and replicated.If X-Agile-Checksum is provided and it does not match the calculated checksum, the file will not be ingested. Instead, error code -26 (invalid checksum) will be returned and the file will be removed from landing pad’s scratch space and will not be ingested. |
Request Payload
The payload consists of the file to upload. For example you could use the following option with curl:
1--data-binary @/tmp/example1.jpg
HTTP Response Codes and Request Status Codes
On success the call returns an HTTP 200 status code and 0 in the X-Agile-Status header.
On error, the HTTP Status Code is an error code, and the error is reflected in the
X-Agile-Status header.The following table provides details about response values.
| HTTP Status Codes | Description | X-Agile-Status Values |
|---|---|---|
| 200 | Success | 0 |
| 400 | Bad request; missing or invalid parameters | -3: parent directory does not exist. You specified a in X-Agile-Directory with a leading path that does not exist and you did not pass a true value in X-Agile-Recursive. -8: invalid path given (path too long). See Path Segment and File Name Limitations. -24: You failed to specify a file to upload. -25: You attempted to upload multiple files. -26: invalid checksum -33: You included an invalid content type in the X-Agile-Content-Type header. -39: You passed an invalid value in the X-Agile-Recursive directory. -51: invalid encoding (You specified an invalid value for the X-Agile-Encoding header.) |
| 401 | Unauthorized, missing X-Agile-Authorization header | -10001: missing X-Agile-Authorization header |
| 403 | Invalid authentication credentials (invalid token) | -10001: invalid token |
| 500 | Internal server error | -5: internal backend service down |
| 503 | Service unavailable | -22: disk full |
Response Headers
| Header Name | Type | Description |
|---|---|---|
| X-Agile-Path | str | File name and path where the file was uploaded. The value will be URI-quoted if UTF8 encoding was used in the X-Agile-Encoding header. |
| X-Agile-Status | int | Contains response codes. (See HTTP Response Codes and Request Status Codes.) |
| X-Agile-Size | int | Size in bytes of the file that was uploaded |
| X-Agile-Checksum | str | File’s SHA-256 hexadecimal digest |
curl Sample Requests
Upload warning.png to the /symbols/warning directory.
1curl -v -k \2-H "X-Agile-Authorization: a1ac4fca-2fed-44ac-9b20-d26aee578e67"\3--data-binary @/tmp/warning.png\4-H "X-Agile-Basename: warning.png"\5-H "X-Agile-Content-Detect: name"\6-H "X-Agile-Content-Type: image/png"\7-H "X-Agile-Directory: /symbols/warning"\8-H "X-Agile-Expose-Egress: POLICY"\9-H "X-Agile-MTime: 0"\10http://{Account name}.upload.llnw.net/post/raw
Sample Success Response
1HTTP/1.1 100 Continue2HTTP/1.1 200 OK3Date: Tue, 23 Jun 2015 20:29:49 GMT4Server Apache is not deny listed5Server: Apache6Access-Control-Allow-Origin: *7Access-Control-Allow-Headers: X-Agile-Authorization, X-Content-Type8Access-Control-Allow-Methods: OPTIONS9X-Agile-Status: 010Content-Length: 011X-Agile-Checksum: da2d48c37dabd94c00bc9dc98aa2ca0255de1a1238e2525ab1d7edce39812X-Agile-Size: 154713X-Agile-Path: /{Account Name}/symbols/warning/warning.png14Content-Type: text/json;charset=utf-8
Content Type Handling
The file upload APIs (/post/file and /post/raw) determine content type as follows:
- The content type specified by the Content-Type field of the attachment (form-data encoded payload1) takes precedence if set.
- The
X-Agile-Content-Typeheader takes precedence overX-Agile-Content-Detect. - The application/octet-stream is special content type, and if you provide it in the
X-Agile-Content-Typeheader, the API attempts to detect the content type from the file name, usually the extension. - If you provide both
X-Agile-Content-TypeandX-Agile-Content-Detect, thenX-Agile-Content-Typetakes precedence. - If you provide neither
X-Agile-Content-TypenorX-Agile-Content-Detect, the API defaults the content type toX-Agile-Content-Detect: auto.
1Here is an example of form-encoded data payload, where the content type is text/plain.
1------------------------------44f9af2ecd0c2Content-Disposition: form-data; name="uploadFile"; filename="test.txt"3Content-Type: text/plain4Sample data5------------------------------44f9af2ecd0c--
Notes
Due to legacy reasons it is possible to pass values (name, content, auto) in
X-Agile-Content-Type that instruct the API to detect the content type, but doing so is not recommended and may result in unpredictable results.The values have the following meanings:
-
name: look up MIME type by using the file name, usually the extension
-
content: look up MIME type by scanning the contents of the file
-
auto: first look up by name, then by content if no name matches
Although the value auto for the
X-Agile-Content-Type header is currently accepted, it will be deprecated at some point in the future. We recommend that you change you code to use alternative means of instructing the API to automatically detect the content type.X-Content-Type Request Header
In the past it was possible to pass the value auto in the legacy
X-Content-Type header to instruct the API to automatically detect the content type of the entity-body, but passing auto causes an error. To cause automatic content detection callers can either:- Omit the
X-Content-Typeheader, or - Pass auto in the
X-Content-Detectheader