Uploading

Creating a library

To create a corporate library, issue the following POST request:

POST /api/libraries

With the following body:

{
    "LibraryName" : <string>,
}

Where:

• LibraryName: the name of the library to be created

Note, an HTTP 400 Bad Request will be returned if the library name is empty. An HTTP 403 Forbidden will be returned if the user is not a site admin, and an HTTP 409 Conflict will be returned if a library with that name already exists. The name "My Library" is reserved.

Creating a new folder

The API gives you the ability to create a new folder at the root of a library or to build out a folder path within a library. To create a folder, issue the following POST request:

POST /api/libraries/{libraryId}/folders

Where:

• libraryId: the ID of the library that contains the folders to be created

With the following body (note that only one value may be specified):

{
    "FolderName" : <string>,
    "FolderPath" : <string>,
    "AutoGenerateName" : <boolean>
}

Where:

• FolderName: the name of the folder to create at the root of the library
• FolderPath: a path to create starting at the root of the library
• AutoGenerateName: a boolean to generate a random GUID as the FolderName, to be created at the root of the library

Note that only FolderName, FolderPath, or AutoGenerateName should be specified. If all three (or any combination of two) parameters are specified, the request will fail with a 400 Bad Request response.

For example:

{
    "FolderName" : "My folder"
}

Is equivalent to:

{
    "FolderPath" : "My folder"
}

Using FolderPath makes it easy to build out folder structures without having to make excessive round trips. This approach will create the full hierarchy if a folder within the hierarchy does not exist. For example, to create folder hierarchies like the following:

Payroll\2015\Development
Payroll\2014\HR

You would POST two separate requests to /api/libraries/{libraryid}/folders specifying the following folder paths:

{ "FolderPath" : "Payroll\\2015\\Development" }
{ "FolderPath" : "Payroll\\2014\\HR" }

The first request will create the Payroll folder along with the 2015 and the Development folders. The second request will recognize that the Payroll folder already exists and will then only create the 2014 and the HR folders.

Uploading documents

Uploads require more code than document downloads since they are subject to network and device limitations that document downloads do not necessarily suffer from.

The API makes it easy to upload documents with either one of two mechanisms. For small documents (less than 5MB), you can upload using a standard multipart HTTP file upload. The multipart upload is simpler, with a single API call and fewer round trips. Large documents (greater than 5MB) may be subject to upload limitations such as network latency and upload timeouts. For that reason, the API provides the ability to stage an upload. Staging an upload in multiple requests provides some benefits, such as allowing for the application to provide status updates and avoiding timeout related issues.

When uploading new documents or revisions with either approach, document names must not contain invalid characters for file names on Windows, e.g. "/".

An HTTP 400 Bad Request will be returned for invalid names and for filetypes not in your configured filetype whitelist.

If a document with the same name and hash already exists in a folder, an HTTP 409 Conflict will be returned. Additionally, this response will be returned when a revision file does not match the current document extension.

Other errors include invalid access, document names being too long, and malformed upload requests.

Uploading small (<5MB) documents

POST /api/folders/{folderId}/documents

Uploading a small document can be done in a single POST using a content type of multipart/form-data. A form should be posted with two fields. The first is a field called metadata that takes the following form:

{"DocumentName":"new picture"}

Where:

• DocumentName: the name of the document to store

The second field is named file and is the contents of the document.

Note, if the DocumentName does not contain an extension, it will use the extension provided by the file in the form.

An example uploading a new document using Javascript would look like the following:

var data = new FormData();
data.append("metadata", "{\"DocumentName\":\"new picture\"}");
data.append("file", --omitted--); // <-From an HTML input field or a byte array

var xhr = new XMLHttpRequest();

xhr.open("POST", "https://app.sharebase.com/sharebaseapi/api/folders/1225/documents");
xhr.setRequestHeader("authorization", "PHOENIX-TOKEN MDAwMDAwMDM6OTU3MzQyZTktOGJiMi00ODdkLTgxOTMtMTdjZDA3NDcwMWNj");

xhr.send(data);

In C# this may look something like the following:

HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "PHOENIX-TOKEN " + "MDAwMDAwMDM6OTU3MzQyZTktOGJiMi00ODdkLTgxOTMtMTdjZDA3NDcwMWNj");
var uri = "https://app.sharebase.com/sharebaseapi/api/folders/1225/documents";
var pathtofile = ""; // get the path to the file from somewhere
FileStream fs = new FileStream(pathtofile, FileMode.Open, FileAccess.Read);

MultipartFormDataContent multipartcontent = new MultipartFormDataContent();

HttpContent filecontent = new StreamContent(fs);

HttpContent metadata = new StringContent("{\"DocumentName\":\"new picture\"});

multipartcontent.Add(filecontent, "file", "nameOfFile.ext");
multipartcontent.Add(metadata, "metadata");

HttpResponseMessage response = await client.PostAsync(uri, multipartcontent);

The contents of the above translates into the following HTTP payload:

POST /sharebaseapi/api/folders/1225/documents HTTP/1.1
Host: app.sharebase.com
Authorization: PHOENIX-TOKEN MDAwMDAwMDM6OTU3MzQyZTktOGJiMi00ODdkLTgxOTMtMTdjZDA3NDcwMWNj
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="metadata"

{"DocumentName":"new picture"}
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename=""
Content-Type:

----WebKitFormBoundary7MA4YWxkTrZu0gW

Updating a small (<5MB) document

The API provides the ability to update an existing document with new revisions:

POST /api/documents/{documentId}/revisions

Similar to a new document, a small document revision can be done in a single POST using a content type of multipart/form-data.

A form should be posted with one field. It should be called file and contain the contents of the document.

Note, the metadata field is not required, as the document name will remain the name in the original upload. The name of the file in the form will become the document revision name.

Uploading large (>5MB) documents

Uploading a large document requires some steps to stage the document in a temporary location before making a final POST to store the document:

• Create a temporary document reference on the server (POST)
• Iterate over the document to upload chunks to the server (PATCH)
• Finalize the upload (POST)

Creating the temporary document

You can stage both a document for storage to a folder as well as stage a revision to a document.

To stage a large upload to a folder, create a temporary document on the server by issuing the following POST request:

POST /api/folders/{folderId}/temp?filename={filename}

Where:

• folderId: the ID of the folder that will receive the document
• filename: the name of the document to store

To stage a large upload as a revision to a document, create a temporary document on the server by issuing the following POST request:

POST /api/documents/{documentId}/revisions/temp?filename={filename}

Where:

• documentId: the ID of the document that will be updated
• filename: the name of the new document revision

For both cases, the body of the POST request should be empty.

The filename query parameter is required for both endpoints. Note, when staging an upload to a folder, the filename provided will become the name of the revision as well as the document name, but when staging an upload as a revision, the filename will only be the name of the revision.

An HTTP 200 OK status code is returned along with a response body like the following:

{
    "Links": {
    "Location": "https://app.sharebase.com/sharebaseapi/api/temp/1/40861735-207d-4972-88f8-79641c74335b"
    },
    "Identifier": "40861735-207d-4972-88f8-79641c74335b",
    "FileName": "new picture.jpg",
    "CurrentSize": 0,
    "VolumeId": 1
}

This response body contains a reference to the temporary document on the server. The reference object has the following properties:

• Identifier: a unique identifier for the document being uploaded
• FileName: the name of the document initially posted
• CurrentSize: the size of the current progress on the server - this can be used by the client to verify the number of bytes it thought it sent down or to indicate progress
• VolumeId: internal use only
• Links:
  • Location: a reference to the document location - PATCH operations can be issued against this link to add data to the document

Uploading portions of the document

To upload the document, issue a PATCH to the location provided in the Links.Location returned by the initial POST. The body of the patch should be the binary data that represents a portion of the document. The recommended size of each chunk is 512KB and not to exceed 2MB. You can issue as many PATCH requests with additional blocks of content as needed.

Finalizing the upload

Once completed, issue a POST to finalize the storage of the document. The final POST is similar to the multipart upload:

For new documents:

POST /api/folders/{folderId}/documents

For revisions:

POST /api/documents/{documentId}/revisions

However, unlike the multipart/form-data upload, the body is empty here, and instead, you must provide a header of x-sharebase-fileref that contains the object returned from the original POST.

x-sharebase-fileref: {...json object from initial temp document response...}

POST /api/folders/{folderId}/documents
x-sharebase-fileref: {"Links": {"Location": "https://app.sharebase.com/sharebaseapi/api/temp/1/40861735-207d-4972-88f8-79641c74335b"},"Identifier":"40861735-207d-4972-88f8-79641c74335b","FileName": "new picture.jpg","CurrentSize": 0,"VolumeId": 1}

An example of uploading a large document with C# can be found here.