File API

Dovetail Seeker has round trip support for both the uploading and download of files.

Download

File downloads APIs are used by Seeker to serve files which have been indexed by Seeker. Dovetail Seeker can also serve attachments related to indexed domains. Additionally there is a Generate Download URL API which Dovetail applications can use to setup the download of any desired file.

Upload Process

Dovetail applications can delegate the responsibility of uploading and storing files to Seeker. This removes the requirement for applications to have write access to corporate file shares.

Generate Download URL

This API should be used to prepare a file to be downloaded from Dovetail Seeker. This API takes a full file path to which Dovetail Seeker has read access and returns a public download URL to which the user's browser will be redirected.

Input

URL:

/seeker/file/url

HTTP Method(s):

Parameters

Parameter Required Default Description
Path Yes N/A Full path of the file the application wishes to serve to the user.
ContentType No application/octet-stream Mime type used to serve the file to the browser.
Expires No 7days Date/Time that the generated token will expire
AlwaysUnique No False Always generate a new token or not

Response:

Parameter Description
Url URL from which this file can be downloaded.
FileName file name which will be served
Id download file token id
Expires Token Expiration date
Examples

Request:

GET /seeker/file/url?Path=\\server\share\path\file.txt

Response:

{
  Url: "http://localhost/seekerproxy/resources/download?Token=download-token-id",
  FileName: "file.txt",
  Id: "download-file-token-id"
}

Upload Process

Dovetail Seeker uploading files is a two step process. First get permission to upload, then have the user directly upload the file to Dovetail Seeker.

The application will first call the private File Upload Token API to create an upload token which will be given to the application user along with the URL where they should upload the file. The upload token grants permission to someone on the Internet to upload a single file into Dovetail Seeker.

The user then directly uploads the file to Dovetail Seeker via the proxied Direct File Upload API.

Upload Process

File Upload Token API

Applications need to call this API before users can upload files. Users will use the results of this API to do a Direct File Upload.

For more details about the upload process take a look at the File Upload Process sequence diagram.

Input

URL:

/seeker/file/upload/token

HTTP Method(s):

Parameters

Parameter Required Default Description
Key Yes N/A Unique key identifying the uploaded file. The key should include a random path segment ensuring it is unique.

This key will be used to create a directory path under which the uploaded file will be stored.

Example: 2014/01/Case/1234/random-ksdfj213kdj87

Note: It is beneficial to attempt to keep directory trees shallow to avoid file performance problems when many files are all put into one directory.
FileName Yes N/A Name of the file to be uploaded.
Timeout No 5 minutes How long should the upload token be valid.

Response:

Parameter Description
ActionURL URL to which the file should be posted
Token Upload permission token which should be posted with the file upload.
Examples

Request:

GET /seeker/file/token?Key=2015/01/case/1234/random-123456abcdedf&FileName=upload.log

Response:

{
  ActionURL: "http://localhost/seekerproxy/file/upload/",
  Token: "biglongrandomtokenstring"
}

Direct File Upload API

The Direct File Upload API is for application users to directly upload files into Dovetail Seeker. This API is proxied and is publicly available. Uploaded files can later be retrieved from the file download API using the file's Key.

Applications will typically setup the web browser to POST to this API using the results returned from the File Upload Token API. After the file is uploaded it is the responsibility of the application to remember the file upload components (key, file name, content type) for future retrieval of the uploaded file.

For more details take a look at the File Upload Process sequence diagram.

Input

URL:

/seeker/file/upload

HTTP Method(s):

Parameters

Parameter Required Default Description
UploadToken Yes N/A The upload token returned by the file upload token API.

When the token is invalid a 404 status will be returned.

When the token has expired a 403 status will be returned.
Files Yes N/A The form used to POST the file should have a file input with a name of "Files".

Only one file can be uploaded at a time.

If no files or more than one file were uploaded a 400 status will be returned.
AlwaysUnique No false Always generate a new token or not
Expires No 1 day Date/Time that the generated token will expire

Response:

Parameter Description
DownloadURL URL from which this file can be downloaded.
Key Key identifying the file uploaded. This value is used to generate a download URL.
Examples

Request:

POST /seeker/file/upload

Response:

{
  DownloadURL: "http://localhost/seekerproxy/file/download/random-download-token-id",
  Key: "2014/01/case/1234/2014/01/Case/1234/random-ksdfj213kdj87"
}