Web API Reference¶
The Web APIs are RESTful APIs that allow access to a subset of gateway functions through a standard HTTP request.
XPort Edge provides the following APIs:
Device Actions API
- Export Status Group - Retrieve device status
- Export Configuration Group - Retrieve device configuration
- Import Configuration Group - Import device configuration
- Take Status Action - Take device status action
File System API
- HTTP GET - Read the contents of files and directories]
- HTTP PUT - Create new files and update existing files
- HTTP MKCOL - Create new directories
- HTTP DELETE - Remove files and directories from the file system
Firmware Upgrade API
- Upgrade Firmware - Load firmware file to gateway
Device Actions API¶
The Device Actions API provide functions to export and import the configuration as well as to export status and take a status action.
These APIs specify a "-d [data]" and use an HTTP content-type of “application/x-ww-form-urlencoded”.
Export Status Group¶
An HTTP POST request can be sent to the device to retrieve status information.
- Protocol: HTTP
- Method: POST
- Content-Type: application/x-ww-form-urlencoded
- URL: http://<hostname>/export/status
Parameters:
- optionalLine: Optional line index for line oriented XML groups
- optionalGroupList: Optional list of XML groups separated by semicolon. If omitted, all status groups will be returned.
CURL example:
curl --anyauth -k -u admin:PASSWORD http://<ip-address>/export/status -X POST
curl --anyauth -k -u admin:PASSWORD http://<ip-address>/export/status -X POST -d "optionalGroupList=Device;Clock"
Javascript example:
myXmlhttprequest.open(
"POST",
"/export/status",
true
);
request.send(
"optionalGroupList=Device"
);
Export Configuration Group¶
An HTTP POST request can be sent to the device to retrieve configuration information.
- Protocol: HTTP
- Method: POST
- Content-Type: application/x-ww-form-urlencoded
- URL: http://<hostname>/export/config
Parameters:
- optionalLine: Optional line index for line oriented XML groups
- optionalGroupList: Optional list of XML groups separated by semicolon. If omitted, all configuration groups will be returned.
- optionalBoolNonDefaultOnly: To retrieve only the configuration which is different from default, set this to “true”.
CURL example:
curl --anyauth -k -u admin:PASSWORD http://<ip-address>/export/config -X POST
curl --anyauth -k -u admin:PASSWORD http://<ip-address>/export/config -X POST -d "optionalGroupList=Interface:wlan0"
Javascript example:
myXmlhttprequest.open(
"POST",
"/export/config",
true
);
request.send(
"optionalGroupList= Interface:wlan0"
);
Import Configuration Group¶
An HTTP POST request can be sent to the device to set configuration.
- Protocol: HTTP
- Method: POST
- Content-Type: multipart/form-data
- URL: http://<hostname>/import/config
Parameters:
- configrecord: Content of configuration group in XML format.
CURL example (configuration is saved in a local file config.xml):
curl --anyauth -k -u admin:PASSWORD http://<ip-address>/import/config -X POST --form configrecord=@config.xml
CURL example (configuration as part of command):
curl --anyauth -k -u admin:PASSWORD http://<ip-address>/import/config -X POST --form-string 'configrecord=<?xml version="1.0" standalone="yes"?>'
<!-- Automatically generated XML -->
<!DOCTYPE configrecord [
<!ELEMENT configrecord (configgroup+)>
<!ELEMENT configgroup (configitem+)>
<!ELEMENT configitem (value+)>
<!ELEMENT value (#PCDATA)>
<!ATTLIST configrecord version CDATA #IMPLIED>
<!ATTLIST configgroup name CDATA #IMPLIED>
<!ATTLIST configgroup instance CDATA #IMPLIED>
<!ATTLIST configitem name CDATA #IMPLIED>
<!ATTLIST configitem instance CDATA #IMPLIED>
<!ATTLIST value name CDATA #IMPLIED>
]>
<configrecord version = "0.1.0.1">
<configgroup name = "Access Point" instance = "ap0">
<configitem name = "SSID">
<value>MY DEVICE</value>
</configitem>
</configgroup>
</configrecord>'
HTTP example:
<form method="post" enctype="multipart/form-data" action="/import/config" target="_blank">
<input name="configrecord" type="file" size="32">
<input name="submit" type="submit" value="Import Configuration">
</form>
Take Status Action¶
An HTTP POST request can be sent to the device to take a status action.
- Protocol: HTTP
- Method: POST
- Content-Type: application/x-ww-form-urlencoded
- URL: http://<hostname>/action/status
Parameters:
- group: Required. The status group where action is defined.
- optionalGroupInstance: Optional instance of status group.
- optionalItem: Optional item of status group where action is defined.
- optionalItemInstance: Optional instance of status item.
- action: Required. The action to be taken. See Actions Definitions for a list of the actions.
CURL example:
curl --anyauth -k -u admin:PASSWORD -X POST -d
"group=Interface&optionalGroupInstance=eth0&action=Renew"
http://<hostname>/action/status
Javascript example:
myXmlhttprequest.open(
"POST",
"/action/status",
true
);
request.send(
"group=Interface&optionalGroupInstance=eth0&action=Renew"
);
Success example:
<?xml version="1.0" standalone="yes"?>
<!-- Automatically generated XML -->
<!DOCTYPE function [
<!ELEMENT function (return)>
<!ELEMENT return (result,message+)>
<!ELEMENT result (#PCDATA)>
<!ELEMENT message (#PCDATA)>
<!ATTLIST function version CDATA #IMPLIED>
]>
<function version = "0.1.0.0">
<return>
<message>Requesting DHCP lease renewal.</message>
<result>Succeeded</result>
</return>
</function>
Failure example:
<?xml version="1.0" standalone="yes"?>
<!-- Automatically generated XML -->
<!DOCTYPE function [
<!ELEMENT function (return)>
<!ELEMENT return (result,message+)>
<!ELEMENT result (#PCDATA)>
<!ELEMENT message (#PCDATA)>
<!ATTLIST function version CDATA #IMPLIED>
]>
<function version = "0.1.0.0">
<return>
<result>Failed</result>
</return>
</function>
Actions Definitions¶
Action definitions related to the Take Status Action API.
NOTE: When you see "NULL" after optionalGroupInstance, optionalItem, or optionalItemInstance, it means that item or instance should be omitted.
Action Groups Index¶
- Clock
- CPM CPs
- CPM Roles
- Device
- File System
- Interface
- Line
- CLI Server
- LPD
- Modbus
- Modem Emulation
- Monitor
- NTP
- SMTP
- Tunnel
- Custom
group "Clock" optionalGroupInstance NULL¶
optionalItem NULL optionalItemInstance NULL¶
action "Current Time <YYYY-MM-DD hh:mm:ss>"¶
The format for setting time is YYYY-MM-DD hh:mm:ss, where the hours are in 24-hour format.
group "CPM" optionalGroupInstance NULL¶
group "CPM CPs" optionalGroupInstance NULL¶
optionalItem "CP" optionalItemInstance Required¶
The optionalItemInstance may range from 1 to 3.
action "Usage <value>"¶
<value> may be "Input", "Output" or "Unused".
action "Assert <value>"¶
<value> may be "High" or "Low".
Assert reflects the logical polarity of this Configurable Pin.
"High" means that a logical "1" corresponds to a voltage high condition on the pin.
"Low" means that a logical "1" corresponds to a voltage low condition on the pin.
action "Mode <value>"¶
<value> may be "Push-Pull" or "Weak Pullup".
action "Value <value>"¶
<value> may be "0" or "1".
Value is the logical value of the Configurable Pin. Its polarity depends on Assert.
"1" represents the "Asserted" state, "0" represents "Not asserted".
group "CPM Roles" optionalGroupInstance NULL¶
optionalItem "Role" optionalItemInstance Required¶
The available Role instances are as follows:
"Ethernet Link" is Link UP while eth0 is up.
"Factory Defaults" active for timed interval will reset configuration to factory defaults.
"HTTP Server Trigger" turns on HTTP Server if Mode is "Triggered".
"Line 1 DSR" read by application.
"Line 1 DTR" set by application.
"Line 1 Flow.CTS" allows send if Flow Control is "Hardware".
"Line 1 Flow.RTS" active says can receive if Flow Control is "Hardware".
"Modbus Input 1" can be read by Modbus TCP.
"Modbus Input 2" can be read by Modbus TCP.
"Modbus Input 3" can be read by Modbus TCP.
"Modbus Input 4" can be read by Modbus TCP.
"Modbus Output 1" can be written by Modbus TCP.
"Modbus Output 2" can be written by Modbus TCP.
"Modbus Output 3" can be written by Modbus TCP.
"Modbus Output 4" can be written by Modbus TCP.
"User Data Updated" is active when user data changes, till Acknowledge action.
action "State <value>"¶
<value> may be "Inactive" or "Active".
If an input role has no CP assigned, the State may be manipulated via the CLI or Web Manager.
group "Device" optionalGroupInstance NULL¶
optionalItem NULL optionalItemInstance NULL¶
action "Save"¶
The Save action works like the "write" command. Any cached configuration changes are committed, so they will apply after a reboot.
Without a Save, any cached configuration changes are lost after a reboot.
optionalItem NULL optionalItemInstance NULL¶
action "Reboot"¶
The Reboot action shuts the device down and restarts it. Any cached configuration changes (those which have not been saved) are lost.
optionalItem NULL optionalItemInstance NULL¶
action "Factory Defaults"¶
The Factory Defaults action restores the device configuration as it came from the factory. Any user changes to configuration are lost.
group "File System" optionalGroupInstance NULL¶
optionalItem NULL optionalItemInstance NULL¶
action "Compact"¶
Compact reorganizes data on the flash file system, recovering dirty space. File data is retained. Note that this happens automatically when attempting to write and no clean space is available, but dirty space is.
optionalItem NULL optionalItemInstance NULL¶
action "Format"¶
Format clears out the flash file system, preserving only system configuration data. Be careful! All other files are destroyed.
group "Interface" optionalGroupInstance Required¶
The optionalGroupInstance must be "eth0".
optionalItem NULL optionalItemInstance NULL¶
action "Renew"¶
The Renew action causes the device to drop its dynamic IP address and request an address from the DHCP server.
group "Line" optionalGroupInstance Required¶
The optionalGroupInstance may be "1", "Virtual_1" or "Virtual_2".
optionalItem NULL optionalItemInstance NULL¶
action "Command <value>"¶
The Command action sends bytes to the Line and picks up bytes in response. The bytes are hex encoded.
Maximum number of characters to read (n) may be specified; default is unlimited.
Milliseconds total time limit (m) may be specified; default is 1000.
Terminating byte (t) may be specified; default is <None>.
Syntax of <value> is:
[n=<decimal number> ][m=<decimal number> ][t=<hex number>
]<hex bytes to send>
First it must successfully open the Line; select Line Protocol of "None" so it may open it successfully.
optionalItem "Receiver" optionalItemInstance NULL¶
action "Receive"¶
The Receive action picks up characters from the Line.
First it must successfully open the Line; select Line Protocol of "None" so it may open it successfully.
action "Hex Receive"¶
The Hex Receive action picks up bytes from the Line.
First it must successfully open the Line; select Line Protocol of "None" so it may open it successfully.
optionalItem "Transmitter" optionalItemInstance NULL¶
action "Transmit <value>"¶
The Transmit action sends characters to the Line.
First it must successfully open the Line; select Line Protocol of "None" so it may open it successfully.
action "Hex Transmit <value>"¶
The Hex Transmit action sends bytes to the Line.
First it must successfully open the Line; select Line Protocol of "None" so it may open it successfully.
group "CLI Server" optionalGroupInstance NULL¶
optionalItem "Telnet" optionalItemInstance NULL¶
action "Kill"¶
The Kill action manually disconnects the active CLI Server connection.
group "LPD" optionalGroupInstance Required¶
The optionalGroupInstance must be "1".
optionalItem NULL optionalItemInstance NULL¶
action "Kill"¶
The Kill action will force the LPD server to kill (abort) any current, active print jobs.
optionalItem NULL optionalItemInstance NULL¶
action "Test Print <number of lines>"
The Test Print action queues a job to the LPD line. Parameter <number of lines> specifies the number of test lines to be printed.
group "Modbus" optionalGroupInstance Required¶
The optionalGroupInstance may be "1", "Virtual_1" or "Virtual_2".
optionalItem "Connection" optionalItemInstance Required¶
The optionalItemInstance may range from 1 to 6.
action "Kill"¶
The Kill action manually disconnects an active Modbus TCP Server connection.
group "Modem Emulation" optionalGroupInstance Required¶
The optionalGroupInstance may be "1", "Virtual_1" or "Virtual_2".
optionalItem "Current Connection" optionalItemInstance NULL¶
action "Kill"¶
The Kill action manually disconnects an active Modem Emulation connection.
group "Monitor" optionalGroupInstance NULL¶
optionalItem "Control" optionalItemInstance Required¶
action "Send"¶
The Send action causes the device to send the associated control message.
group "NTP" optionalGroupInstance NULL¶
optionalItem NULL optionalItemInstance NULL¶
action "Sync"¶
The Sync action requests immediate clock synchronization with the NTP server.
group "SMTP" optionalGroupInstance NULL¶
optionalItem NULL optionalItemInstance NULL¶
action "Send <value>"¶
Note: The Send action is not available to the web API.
Example usage:
Send <ssl server hostname>
<username>
<password>
<from mail address>
<first recipient mail address>
[optional second recipient mail address]
[...] <-- Empty line ends recipient list
<subject>
<first line of body>
[optional second line of body]
[...] <-- Empty line ends body
group "Tunnel" optionalGroupInstance Required¶
The optionalGroupInstance may be "1", "Virtual_1" or "Virtual_2".
optionalItem "Current Connection" optionalItemInstance Required¶
Possible instance names are "Accept" and "Connect <n>", where <n> is the Host number, for example "Connect 1".
action "Kill"¶
The Kill action manually disconnects an active Tunnel connection.
group "Custom" optionalGroupInstance NULL¶
optionalItem NULL optionalItemInstance NULL¶
action "Acknowledge"¶
The Acknowledge action deasserts the "User Data Updated" CP until the next configuration change.
File System Web API¶
The File System Web API is a RESTful cloud API which allows basic manipulation of file system nodes (files and directories). It is intended to support web-based file system access without the need of a browser, and as such can be used in scripts with HTTP programs such as cURL.
Supported file system node operations are implemented via various HTTP request types. The File System Web API uses standard HTTP requests as well as HTTP extensions from the Web Distributed Authoring and Versioning (WebDAV) standard.
Four principal HTTP requests are implemented by the API: GET, PUT, MKCOL, and DELETE.
HTTP GET¶
Used to obtain, or “read”, the contents of files and directories in the file system.
URL: http://<hostname>/fs/[node]
Where node can be a file, in which case the file content is returned; or a directory, in which case an XML-formatted list of directory objects is returned.
HTTP Response Codes:
- 200: Success
- 404: Node not found
Example:
# curl --anyauth -k –s –u admin:PASSWORD http://192.168.0.1/fs/embedded
<!-- Automatically generated XML -->
<!DOCTYPE directorylist [
<!ELEMENT dentry (name,size)>
<!ELEMENT name (#CDATA)>
<!ELEMENT size (#CDATA)>
<!ATTLIST dentry type CDATA #IMPLIED>
<!ATTLIST directorylist path CDATA #IMPLIED>
]>
<directorylist path = "/embedded">
<dentry type = directory>
<name>main</name>
<size>0</size>
</dentry>
<dentry type = directory>
<name>modem_emulation</name>
<size>0</size>
</dentry>
<dentry type = directory>
<name>monitor</name>
<size>0</size>
</dentry>
<dentry type = directory>
<name>ntp</name>
<size>0</size>
</dentry>
<dentry type = directory>
<name>query_port</name>
<size>0</size>
</dentry>
<dentry type = directory>
<name>tunnel</name>
<size>0</size>
</dentry>
<dentry type = directory>
<name>user_data</name>
<size>0</size>
</dentry>
</directorylist>
HTTP PUT¶
Used to place new files in the file system and update existing files. Directories cannot be created using PUT; the MKCOL request must be used.
Note that PUT will overwrite an existing file by the same name.
URL: http://<hostname>/fs/[path]/file
HTTP Response Codes:
- 201: File successfully created. This code is part of the WebDAV standard.
- 509: Not enough space
- 500: Other failure
Example:
> ls -l
-rw-r--r-- 1 user wheel 166 Oct 22 2013 file.txt
> curl --anyauth -k –s –u admin:PASSWORD http://192.168.0.1/fs/ -T file.txt
> curl --anyauth -k –s –u admin:PASSWORD http://192.168.0.1/fs/
<!-- Automatically generated XML -->
<!DOCTYPE directorylist [
<!ELEMENT dentry (name,size)>
<!ELEMENT name (#CDATA)>
<!ELEMENT size (#CDATA)>
<!ATTLIST dentry type CDATA #IMPLIED>
<!ATTLIST directorylist path CDATA #IMPLIED>
]>
<directorylist path = "/embedded">
<dentry type = file>
<name>file.txt</name>
<size>166</size>
</dentry>
</directorylist>
HTTP MKCOL¶
Used to create new directories (not files) in the file system. MKCOL (“make collection”) is an HTTP extension from the WebDAV standard.
URL: http://<hostname>/fs/[path]/directory
HTTP Response Codes:
- 201: Directory successfully created. This code is part of the WebDAV standard.
- 409: Directory already exists
- 500: Other failure
Example:
> curl --anyauth -k –s –u admin:PASSWORD http://192.168.0.1/fs/dir1 -X MKCOL
> curl --anyauth -k –s –u admin:PASSWORD http://192.168.0.1/fs/
<!-- Automatically generated XML -->
<!DOCTYPE directorylist [
<!ELEMENT dentry (name,size)>
<!ELEMENT name (#CDATA)>
<!ELEMENT size (#CDATA)>
<!ATTLIST dentry type CDATA #IMPLIED>
<!ATTLIST directorylist path CDATA #IMPLIED>
]>
<directorylist path = "/embedded">
<dentry type = file>
<name>file.txt</name>
<size>166</size>
</dentry>
<dentry type = directory>
<name>dir1</name>
<size>0</size>
</dentry>
</directorylist>
HTTP DELETE¶
Used to remove files and directories from the file system.
URL: http://<hostname>/fs/[path]/node
Where node can be either a file or directory.
HTTP Response Codes:
- 204: No content (node successfully removed). This code is part of the WebDAV standard.
- 404: Node not found
- 500: Other failure
Example:
> curl --anyauth -k –s –u admin:PASSWORD http://192.168.0.1/fs/file.txt -X DELETE
> curl --anyauth -k –s –u admin:PASSWORD http://192.168.0.1/fs/
<!-- Automatically generated XML -->
<!DOCTYPE directorylist [
<!ELEMENT dentry (name,size)>
<!ELEMENT name (#CDATA)>
<!ELEMENT size (#CDATA)>
<!ATTLIST dentry type CDATA #IMPLIED>
<!ATTLIST directorylist path CDATA #IMPLIED>
]>
<directorylist path = "/embedded">
<dentry type = directory>
<name>dir1</name>
<size>0</size>
</dentry>
</directorylist>
Firmware Upgrade API¶
The firmware upgrade API allows the device to upgrade the firmware image. The request format emulates a filled-in form to produce a POST request with an HTTP content-type of “multipart/form-data”.
This differs from the status/configuration APIs, which specify a "-d [data]" and use an HTTP content-type of “application/x-ww-form-urlencoded”, or the File System APIs, which use standard HTTP requests and HTTP extensions from WebDAV.
Firmware Upgrade¶
- Description: Load the firmware image file
- Protocol: HTTP
- Method: POST
- Content Type: multipart/form-data
- URL: http://<hostname>/upgrade
Parameters:
- imageFile: Name of the file containing the upgrade image.
HTTP Response Codes:
- 200: Success
- 507: Invalid partition size
- 500: All other failures
CURL example:
curl --anyauth -k –u admin:PASSWORD –X POST http://<hostname>/upgrade -F imageFile=@xPico200_1.6.0.0R58