HTTP API

WebDat and ExpeDat Desktop each provide an HTTP based API server on the local loopback interface.  A webpage in a local browser can use this to initiate data transfers and monitor their status.  In the case of WebDat, the webpage provides the primary user interface.

ExpeDat Desktop http://127.0.0.1:8090/
WebDat http://127.0.0.1:8091/

Once installed, WebDat's API server is available persistently on port 8091.  ExpeDat Desktop is available on port 8090 only after being launched either from the webpage invoking an expedat:// URL or manually by the user.  Both clients provide the following actions via the HTTP GET method:

id Verifies that the client is running and returns version and license information.
url_exec Posts an expedat:// URL for execution.
url_status Monitors the status of a previously posted expedat:// URL.

Each method returns a JSON formatted response.  If more than one instance of the same client is running, only one will be able to respond to HTTP requests.  If that instance quits, it may be necessary to restart all instances of that client type.

HTTP Responses

The following HTTP responses may be returned:

200 OK The request was understood and the response is a JSON object.
400 Session ID required url_status did not provide a Session ID.
400 Query must be an expedat:// URL url_exec did not provide an expedat:// URL.
405 Method Not Allowed Only GET, OPTIONS, and HEAD methods are permitted.  Only the GET method performs actions.
410 Session ID not found The Session ID given to url_status is invalid or has timed out.
500 Internal Error Something went wrong while processing this request, most likely an out-of-memory condition.

Security

To ensure the integrity of the host system, HTTP connections are only allowed via the loopback or 127.0.0.1 address.

WebDat:  The user will be prompted to select files and folders for each upload and a destination folder for each download.  The user may abort all active sessions at any time using the WebDat notification menu.

ExpeDat Desktop:  The first time url_exec is run, the user will be asked whether they wish to allow the website to control ExpeDat Desktop.  If the user approves, then url_exec will return a Controller ID which can be used on subsequent actions to avoid further user prompts.

Life Cycle

ExpeDat Desktop should be used where most interactivity will occur directly with the ExpeDat client.  This option requires the least webpage development.  A webpage can test whether ExpeDat Desktop is running by attempting an id on port 8090.  If the connection fails, the webpage should execute an "expedat://" URL to attempt a launch of ExpeDat Desktop.  Repeat the id attempt after several seconds.  If it still fails, prompt the user to download ExpeDat Desktop.

WebDat should be used when the webpage can provide a complete user interface for all intended transactions.  A webpage can test whether WebDat is installed by attempting an id on port 8091.  If the connection fails, the webpage should prompt the user to download and install WebDat.

The EXP JavaScript API can build expedat:// URLs, which are then executed via the HTTP interface.

A typical session might follow these steps:

  1. Use id to check whether a client is running, as described above.
  2. Call EXP_MakeURL() to generate an upload, download, or other ExpeDat request.
  3. Use url_exec to post this request to the HTTP API.  The user will be prompted as described in Security above.  Save the returned Session ID and, for ExpeDat Desktop, the Controller ID.
  4. Use url_status with the Session ID to periodically check the progress of the action.
  5. Additional URLs may be generated and run.  For ExpeDat Desktop, use the Controller ID to avoid repeating the user prompt.

In the current implementation, Session IDs will timeout 5 minutes after the session completes and Controller IDs will expire 30 minutes after the last action.  There is no fixed limit to the number Sessions that can be tracked.  At most 16 Controller IDs may be active, with new IDs replacing the oldest once that limit is reached.  These values may change in future updates.

Action id

The id action can be used to determine whether a client is currently running and retrieve its version and license information.

Example

http://127.0.0.1:8090/id { "name": "ExpeDat Desktop", "title": "ExpeDat Desktop", "version": 1190100, "MTPappstr": "ExpeDat Desktop - 1.19.1 December 2020 - DEI, EXP-1.19.1, DOC-2.3.5 MTP-osx-4.3.2 3563", "MTPlicstr": "00000001: ExpeDat-1.19B Data Expedition Inc., DataExpedition.com" }

Arguments

None

Optional Headers

X-ExpeDat-Controller-ID
ExpeDat Desktop Only 		The controller ID number from your most recent url_exec.

JSON Response Fields

name The name of the ExpeDat client.
title The name of the executable.  If executable name has been customized, that name will appear here.
version The client version number as an integer value.  Useful for detecting whether a minimum version requirement is met.
MTPappstr The full version description of the client, as would be seen in its About box.
MTPlicstr The client license description, as would be seen in its About box.

See Tech Note 0001 for details about MTP version numbering and strings.

Effects

ExpeDat Desktop: If the X-ExpeDat-Controller-ID header is given, and the ID is valid, the idle timer for that ID is reset.  Your web application can keep its Controller ID alive by periodically calling the id action.

Action url_exec

The url_exec action posts an expedat:// URL to the client for execution.  It is functionally similar to clicking on a link, with the following benefits:

Example

http://127.0.0.1:8090/url_exec?expedat://example.com/testfile.dat?u=user&p=password { "session_id": "4F16D92C651999A4", "controller_id": "392D3BB57091E3B2" }

Arguments

The query string must be the expedat:// URL to be executed.

Optional Headers

X-ExpeDat-Controller-ID
ExpeDat Desktop Only 		The controller ID number from your most recent url_exec.  May be omitted if this is the first url_exec.
X-ExpeDat-Controller-Name
ExpeDat Desktop Only 		A brief description of the webpage, which will be presented to the user when asking for their permission to allow the site to control ExpeDat Desktop.  For maximum security, you should include a PIN or other unique information that is displayed to the user in your webpage.  If omitted, "an unnamed webpage" will be used.
X-ExpeDat-Options
WebDat Only 		A JSON object containing user preferences to apply to this transaction.

{ streaming: <Boolean>, /* True to use Streaming Folders for folder transfers */ aggression: <Integer>, /* An SDK aggression value (128 ± user value) */ expire: <Integer>, /* Transaction timeout in seconds */ maxrate: <Integer>, /* Maximum speed in kiloBITS per second */ }

X-ExpeDat-Filter
WebDat Only 		A semi-colon separated list of case-insensitive glob patterns to be applied to user selected files.  See Filters below.  For example, the following would allow the user to only select PDF and TXT files:
X-ExpeDat-Filter:*.pdf;*.txt

JSON Response Fields

session_id Use this string with url_status to monitor the status and progress of this action.
controller_id
ExpeDat Desktop Only 		If a valid X-ExpeDat-Controller-ID header was provided, the same value will be returned.  Otherwise, a new controller ID will be returned.

Effects

The expedat:// URL will be queued for execution and the HTTP request will return immediately.  url_status may be used to track the results.

For ExpeDat Desktop, if the X-ExpeDat-Controller-ID header is missing or invalid, the user will be asked whether they wish to allow the webpage named by the X-ExpeDat-Controller-Name header to control ExpeDat Desktop.  If the user refuses, no further action will be taken and the Controller ID returned will not be valid.  If the user accepts, then the URL will be executed and future url_exec calls using that Controller ID will not prompt the user for permission.

Providing an invalid Controller ID is the same as providing no ID: it does no harm other than prompting the user for permission.  Because both the webpage and ExpeDat Desktop may be restarted at any time, expect that a Controller ID may become invalid at any time and always provide the latest one in all requests.

Because WebDat does not have a persistent user interface, it always prompts the user for download locations and upload files and so does not require a Controller ID.

Action url_status

Retrieve status information for a previous url_exec session.  Status information includes the current state of the action as well as the state and progress of any file transfers which result from it.  For example, a single url_exec might trigger a one-at-a-time folder transfer consisting of hundreds or even thousands of file transfers.

ExpeDat Desktop and WebDat have different runtime models and will report progress slightly differently.  With Expedat Desktop, a user may directly perform file transfers, browse and manipulate files, and respond to warnings and other prompts.  This may delay or change operations submitted through the HTTP API.  With WebDat, all operations are queued through the HTTP API and the user is not prompted for warnings or error conditions.  WebDat sessions will terminate immediately if there is a problem requiring user interaction.

Example

http://127.0.0.1:8090/url_status?175E4C65248F6FCB { "175E4C65248F6FCB": { "session_id": "175E4C65248F6FCB", "url": "expedat://example.com/testfile.dat?u=user&p=password", "state_int": 5, "state_string": "Done", "error_class": 0, "error_code": 0, "error_string": "", "start": 1589984494, "transferred": 52428800, "targets": 1, "current": 1, "progress": { "start": 1589984499, "bytes": 50997024, "eta": 0, "speed": 25661289 }, "results": [ { "target": "testfile.dat", "error_class": 0, "error_code": 0, "error_string": "", "transferred": 52428800, "size": 52428800 } ] } }

Arguments

The query string must be the Session ID from a previous url_exec.

Optional Headers

X-ExpeDat-Controller-ID
ExpeDat Desktop Only 		The controller ID number from your most recent url_exec.

JSON Response Fields

session_id The Session ID given as the argument.
url The original expedat:// URL used to start this session.
state_int A numerical indication of the progress of this session.
1 - Waiting The action is waiting for user interaction, possibly from other actions.
2 - Queued The session is approved and network transactions have queued for execution.
3 - Active A network transaction related to this session is now running.
4 - Prompting ExpeDat Desktop is waiting for user feedback.
5 - Done No further actions are pending for this session.  The session status will remain available for a few minutes, then it will be removed and the Session ID will become invalid.
state_string A human readable description of the session state.
error_class A non-zero value indicates that one or more errors have occurred.  A value of 255 indicates that there were multiple results.  See the results array for details.  Otherwise an MTP Error Class value indicates the source of the error.  See Tech Note 0013 for MTP Error Class definitions.
error_code The MTP Error Code for the given MTP Error Class.  See Tech Note 0013 for MTP Error Code definitions.
error_string If error_class is non-zero, this will be a human readable description of the error.
start The unix time when this session began.
transferred The total number of bytes transferred so far by this session.
expected
WebDat Only 		The estimated total number of bytes expected to be transferred by this session.  This field will be zero if the amount cannot be calculated, such as when Streaming Folders is enabled and a folder is selected.
targets The number of elements in the results array.
current The zero based index of the currently active element in the results array.  This value may be equal to targets when processing is complete.
progress Ephemeral information about the progress of the currently active element.
start Unix time when this element began transferring data.
speed Current estimated speed in bits per second.
eta Estimated seconds remaining, if known.
results An array of status information for each file target of the session.  For ExpeDat Desktop, each folder selected by the user is given a single summary result.  For WebDat, each item in each selected folder is given its own results entry when Streaming Folders is disabled.  This allows WebDat clients to see the entire list of files being uploaded.
target The base name of the file being transferred.
error_class A non-zero value indicates that an error has occurred and where it originated.  See Tech Note 0013 for MTP Error Class definitions.
error_code The specific error within the given error_class.  See Tech Note 0013 for MTP Error Code definitions.
error_string If error_class is non-zero, this will be a human readable description of the error.
transferred The number of bytes successfully transferred so far.
size The total size of this file, when known.  For some transactions, such as downloading a large S3 object, the total size may not be known until the transfer is complete.

Note that Streaming Folders transfers treat the entire folder as a single target.

Effects

If the X-ExpeDat-Controller-ID header is given, and the ID is valid, the idle timer for that ID is reset.

Filters

The X-ExpeDat-Filter header used by WebDat allows you to limit which files a user may select for upload.  It is applied to user upload selections and the contents of non-streaming folder transfers.  The header value consists of glob-like patterns with similar syntax to the Linux fnmatch function and the following distinctions:

For example, "*.pdf;*.txt;*.doc" will match only files with the extension PDF, TXT, or DOC.