HTTP API

Web pages can communicate directly with a local ExpeDat Desktop to initiate data transfers and monitor their status.  Once ExpeDat Desktop has been launched using an expedat:// URL, calls to http://127.0.0.1:8090/ will allow local web applications to create and maintain their own browser-based interface.  The following actions are supported via the HTTP GET method:

id Verifies that ExpeDat Desktop 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 ExpeDat Desktop instance is running, only one will respond to HTTP requests.  If that instance quits, it may be necessary to quit all instances before HTTP connectivity can be restored by launching a new one.

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.

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 the Controller ID returned by url_exec can be used on subsequent actions to avoid further user prompts and keep the ID number active.

Life Cycle

Web pages typically use the EXP JavaScript API to launch ExpeDat Desktop and build expedat:// URLs, which are then executed via the HTTP interface.  These steps are commonly followed:

  1. Use id to check whether ExpeDat Desktop is already running.
  2. If it is not running, use EXP_DoURL("expedat://") to launch ExpeDat Desktop then repeat the /id check.
  3. Call EXP_MakeURL() to generate an upload, download, or other ExpeDat request.
  4. Use url_exec to post this request to ExpeDat Desktop.  The user will be asked whether they wish to allow your webpage to control ExpeDat Desktop.  Save the returned Session ID and Controller ID.
  5. Use url_status with the Session ID to periodically check the progress of the action.
  6. Additional URLs may be generated and run.  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 ExpeDat Desktop 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 The controller ID number from your most recent url_exec.

JSON Response Fields

name The name of the ExpeDat client.  Currently, this should always be ExpeDat Desktop.
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

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 ExpeDat Desktop for execution.  It is functionally similar to clicking on a link, with the following exceptions:

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 The controller ID number from your most recent url_exec.  May be omitted if this is the first url_exec.
X-ExpeDat-Controller-Name 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.

JSON Response Fields

session_id Use this string with url_status to monitor the status and progress of this action.
controller_id 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.

If the X-ExpeDat-Controller-ID header is missing or does not contain a valid ID, 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.

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.

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 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.
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.
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.