magicVORTEX HTTPAPI Documentation version 1

Purpose

To provide a standards-based, easy-to-implement protocol for automated file transfer. Emphasis has been placed on repeatibility and unattended operation. User interaction is not a design goal of this protocol.

The magicVORTEX HTTPAPI is an extension of HTTP/1.1. The specifications of such are documented in RFC 2616: Hypertext Transfer Protocol HTTP/1.1 and is available at http://www.w3.org.

Actions


Abort

Cancels the transfer while the file is still active. Can be performed by sender or recipient of the file.

Syntax

GET https://magicvortex.com/HTTPAPI/1/dispatch.vortex?Action=Abort&FileID=xSijIzDtQw@mtS5bVo42AH

Parameters

Action = "Abort"
FileID = The FileID of the file to abort

Authentication

Authentication Scheme = Basic
UserID = magicVORTEX Primary Email Address
Password = magicVORTEX Password
Realm = "magicVORTEX"

Request Content

none

Response Content

none

Response Codes

200 = Successfully aborted file
400 = Invalid Action specified
401 = Account email address and password are required
402 = Account usage restricted
403 = Authentication failed
405 = Only GET method is allowed
406 = FileID is invalid or ineligible for abort
500 = Unexpected service error


Confirm

Confirms successful transmission of file to the sender. Perform this action only after a successful Receive action on the same file.

Syntax

GET https://magicvortex.com/HTTPAPI/1/dispatch.vortex?Action=Confirm&FileID=xSijIzDtQw@mtS5bVo42AH

Parameters

Action = "Confirm"
FileID = The FileID of the file to confirm

Authentication

Authentication Scheme = Basic
UserID = magicVORTEX Primary Email Address
Password = magicVORTEX Password
Realm = "magicVORTEX"

Request Content

none

Response Content

none

Response Codes

200 = Successfully confirmed file
400 = Invalid Action specified
401 = Account email address and password are required
402 = Account usage restricted
403 = Authentication failed
405 = Only GET method is allowed
406 = FileID is invalid or ineligible for confirm
500 = Unexpected service error


Help

Displays this document.

Syntax

GET http://magicvortex.com/HTTPAPI/1/dispatch.vortex?Action=Help

Parameters

Action = "Help"

Authentication

none

Request Content

none

Response Content

XHTML 1.0 document containing these specifications. Encoding: UTF-8

Response Codes

200 = Successful
400 = Invalid Action specified
500 = Unexpected service error


List

Retrieves the list of active files. Perform this action before attempting to Receive a file.

Syntax

GET https://magicvortex.com/HTTPAPI/1/dispatch.vortex?Action=List

Parameters

Action = "List"

Authentication

Authentication Scheme = Basic
UserID = magicVORTEX Primary Email Address
Password = magicVORTEX Password
Realm = "magicVORTEX"

Request Content

none

Response Content

XML 1.0 document listing all active files. Encoding: UTF-8

<?xml version="1.0" encoding="UTF-8"?>
<TransferInventory xmlns="http://magicvortex.com/HTTPAPI/1/TransferInventory.xsd">
  <Sent>
    <File
      FileID="xSijIzDtQw@mtS5bVo42AH"
      Filename="file1.xml"
      FileDate="2003-02-14T12:00:00.000Z"
      FileSize="76867"
      Description="This is the first file."
      PublishDate="2003-07-01T16:16:36.000Z"
      ExpirationDate="2003-07-15T16:16:36.000Z"
      SenderAddress="&quot;John Doe&quot; &lt;johnd@abc.com&gt;"
      RecipientAddress="&quot;Bill Smith&quot; &lt;bill.smith@xyz.net&gt;"
    />
    <File
      FileID="mjfiuJl345^khG345Ifgw@"
      Filename="file2.xml"
      FileDate="2003-04-24T14:34:12.000Z"
      FileSize="55296"
      PublishDate="2003-06-30T16:16:36.000Z"
      ExpirationDate="2003-07-14T16:16:36.000Z"
      FinalizeDate="2003-06-30T16:17:36.000Z"
      SenderAddress="&quot;John Doe&quot; &lt;johnd@abc.com&gt;"
      RecipientAddress="&quot;Bill Smith&quot; &lt;bill.smith@xyz.net&gt;"
    />
  </Sent>
  <Received>
    <File
      FileID="8hHg7gFe1ih@hdhup928jf"
      Filename="file3.xml"
      FileDate="2003-05-21T16:03:00.000Z"
      FileSize="51998"
      PublishDate="2003-06-29T09:56:27.000Z"
      ExpirationDate="2003-07-06T09:56:27.000Z"
      SenderAddress="&quot;Sue Doogan&quot; &lt;sdoogan@company.com&gt;"
      RecipientAddress="&quot;John Doe&quot; &lt;johnd@abc.com&gt;"
    />
    <File
      FileID="PkdhSsR9h38hf3jhkZd3FD"
      Filename="file4.xml"
      FileDate="2003-06-12T12:01:01.000Z"
      FileSize="48480"
      Description="Updated XML file for 6/12/03"
      PublishDate="2003-06-30T14:14:46.000Z"
      ExpirationDate="2003-07-07T14:14:46.000Z"
      FinalizeDate="2003-06-30T20:21:33.000Z"
      SenderAddress="&quot;Sue Doogan&quot; &lt;sdoogan@company.com&gt;"
      RecipientAddress="&quot;John Doe&quot; &lt;johnd@abc.com&gt;"
    />
  </Received>
</TransferInventory>

Schema

http://magicvortex.com/HTTPAPI/1/TransferInventory.xsd

Response Codes

200 = Successful
400 = Invalid Action specified
401 = Account email address and password are required
402 = Account usage restricted
403 = Authentication failed
405 = Only GET method is allowed
500 = Unexpected service error


Receive

Receives a file. Perform this action after discovering an active file from a List action.

Syntax

GET https://magicvortex.com/HTTPAPI/1/dispatch.vortex?Action=Receive&FileID=xSijIzDtQw@mtS5bVo42AH

Parameters

Action = "Receive"
FileID = The FileID of the file to receive

Authentication

Authentication Scheme = Basic
UserID = magicVORTEX Primary Email Address
Password = magicVORTEX Password
Realm = "magicVORTEX"

Request Content

none

Response Content

Binary contents of file.

Response Codes

200 = Successfully received the file
400 = Invalid Action specified
401 = Account email address and password are required
402 = Account usage restricted
403 = Authentication failed
405 = Only GET method is allowed
406 = FileID is invalid or ineligible for receive
500 = Unexpected service error


Send

Sends a file. Perform this action after performing a Verify action with the transfer instructions.

Syntax

POST https://magicvortex.com/HTTPAPI/1/dispatch.vortex?Action=Send&Filename=file1.xml&Recipients=bill.smith@xyz.net;sdoogan@company.com&Confirmation=true&Description=This+is+the+first+file.

Parameters

Action = "Send"
Filename = The name of the file to send.
Recipients = A list of SMTP email addresses separated by semicolons (;).
Confirmation = ("true" | "false") If set to true, an email confirmation will be sent to the sender upon transfer completion.
Description = (optional) Attaches a short description to the file transfer. Maximum characters: 255

Authentication

Authentication Scheme = Basic
UserID = magicVORTEX Primary Email Address
Password = magicVORTEX Password
Realm = "magicVORTEX"

Request Content

Binary contents of file.

Response Content

XML 1.0 document detailing the successfully sent files. Encoding: UTF-8

<?xml version="1.0" encoding="UTF-8"?>
<SendResults xmlns="http://magicvortex.com/HTTPAPI/1/SendResults.xsd">
  <Recipient
    RecipientAddress="&quot;Bill Smith&quot; &lt;bill.smith@xyz.net&gt;"
    FileID="xSijIzDtQw@mtS5bVo42AH"
  />
  <Recipient
    RecipientAddress="&quot;Bill Smith&quot; &lt;bill.smith@xyz.net&gt;"
    FileID="mjfiuJl345^khG345Ifgw@"
  />
</SendResults>

Schema

http://magicvortex.com/HTTPAPI/1/SendResults.xsd

Response Codes

200 = Successfully sent file
400 = Invalid Action specified
401 = Account email address and password are required
402 = Account usage restricted
403 = Authentication failed
404 = Bad recipient address(es)
405 = Only POST method is allowed
406 = Bad or missing posted data
413 = Posted data exceeds available transfer limit
414 = Too many recipients
500 = Unexpected service error


Verify

Verifies that a Send action will be accepted. Saves considerable upload time by proofing transfer details before transmission.

Syntax

GET https://magicvortex.com/HTTPAPI/1/dispatch.vortex?Action=Verify&Recipients=bill.smith@xyz.net;sdoogan@company.com&Size=10832933

Parameters

Action = "Verify"
Recipients = A list of SMTP email addresses separated by semicolons (;).
Size = The size of the file to send in bytes. Maximum file size: 2147483647

Authentication

Authentication Scheme = Basic
UserID = magicVORTEX Primary Email Address
Password = magicVORTEX Password
Realm = "magicVORTEX"

Request Content

none

Response Content

none

Response Codes

200 = Successfully verified file
400 = Invalid Action specified
401 = Account email address and password are required
402 = Account usage restricted
403 = Authentication failed
404 = Bad recipient address(es)
405 = Only GET method is allowed
406 = Bad or missing Size
413 = Size exceeds available transfer limit
414 = Too many recipients
500 = Unexpected service error