Uploading Files from a Web Browser

In addition to allowing objects to be added to the ScaleOut service via an HTTP PUT request, the ScaleOut REST API allows objects to be added via HTTP POST requests—this facilitates uploading a file directly into the ScaleOut service from an HTML form. Only one file may be uploaded per request.

Unlike most operations in the REST API, POST requests do not rely on HTTP headers to supply additional arguments. Instead, form fields in the request are used to set policies and options for the uploaded file.

<!-- Example: Simple HTML form to upload a file to the "MyNamespace"
     namespace with a user-specified ID -->

<form id="UploadForm" action="/MyNamespace" method="POST" enctype="multipart/form-data">
  ID: <input type="text" name="Soss-Key" /><br/>
      <input type="file" name="fileContent" multiple="false"/><br/>
      <input type="submit" value="POST File" />
</form>
[Note] Note

Form content must be submitted to the REST service using multipart/form-data encoding.

Request

POST /data/{Namespace}
Request Form Fields
Soss-Key
(Optional) Key to the object being stored. If omitted, the service will use the uploaded file’s name (including its extension, but not its full path) as the key to the object in the ScaleOut service.
Soss-Namespace
(Optional) Namespace in which the object will be stored. If omitted, the service will use the namespace provided in the <form> element’s action attribute.
Soss-TimeoutSec
(Optional) Specifies the lifetime of the object in seconds. The default is an infinite timeout (0).
Soss-TimeoutType

(Optional) Specifies one of three valid timeout types. The default is an Absolute timeout:

  • Absolute: The object uses an absolute timeout (default).
  • Sliding: The object uses a sliding timeout that is reset every time an object is accessed (either updated or retrieved).
  • ResetOnUpdate: The object’s timeout is reset when the object is updated, but it is not reset if the object is retrieved.
Soss-EnableLRU

(Optional) Specifies whether the object is subject to LRU (least-recently used) eviction in low memory situations. The default is subject to eviction, or the namespace’s default value if present in the configuration file:

  • true: The object is subject to LRU eviction.
  • false: The object is not subject to LRU eviction.
Soss-EnableReplication

(Optional) Specifies whether the object is eligible for GeoServer push replication. The default is eligible for replication, or the namespace’s default value if present in the configuration file:

  • true: The object is eligible for GeoServer replication.
  • false: The object is not eligible for GeoServer replication.

Response

If successful, the response will contain an empty message body. If an unexpected error occurs, the response’s message body will contain detailed error information in a JSON document (see Errors for more information).

Response Status Codes
201
Success (HTTP Created). The POST request resulted in the creation of a new object.
204
Success (HTTP No Content). The POST request successfully updated an object that already existed in the ScaleOut service.
400
Bad Request. One or more parameters were invalid.
500
Internal Server Error. The server could not read the file.
501
Not implemented. The request attempted to upload more than one file.
Response Headers
ETag
An opaque, quoted entity tag value that indicates the current version of the object that has just been created/updated by the caller. This value can be used in later requests to perform cache validation or optimistic updates to the object. (See RFC2616 sec. 14.19 for details on HTTP entity tags.)