HTTP API Reference

Channel API functions

Contents

The HTTP Channel API allows you to use an HTTP connection to manipulate the channels on local or remote Iguana instances.

The functions for this module are:

  • add_channel : Adds a new channel to the Iguana server
  • current_version : Returns a table containing version information for the Iguana server
  • export_project : Retrieves a zip file containing the contents of a Translator project
  • get_channel_config : Retrieves the configuration for a channel serialized as XML
  • get_default_config : Returns the default configuration for a channel with the specified components
  • get_server_salt : Retrieves the salt used by the Iguana server for encryption purposes
  • import_project : Sets the contents of a Translator project to the contents of a project zip file
  • remove_channel : Removes a channel from the Iguana server
  • save_project_milestone : Saves a milestone for the specified Translator project
  • status : Returns a XML report with information on the server itself and the channels within it
  • update_channel : Updates the configuration of an existing channel

Note: The “Usage” examples given below use the Translator net.http.post() function. Equivalent HTTP calls can be written in any language.

The HTTP API portion of the command is highlighted in bold, the remainder is simply the the net.http.post() used to deliver the command.

add_channel [top]

Usage:

net.http.post{url='<value>/add_channel‘,

auth={password=<value>, username=<value>},

parameters={config=<value> [, compact=<value>] },

live=<true/false>

}

Adds a new channel to the Iguana server. The channel added must have a unique name. This operation requires the user to have administrator privileges.

Can be used in conjunction with the get_default_config handler to create new channels from scratch, or with get_channel_config to clone existing channels.

Tip: Adding or configuring From Channel source components is a bit tricky, because the From Channel settings do not store the configuration settings. The configuration for From Channel components is actually stored in the dequeue_list element within the configuration for the destination component of the channel.

See Configuring a From Channel component using the HTTP Channel API for more information.

Returns:

  • The configuration of the newly added channel. MIME type: application/xml.

Required parameters:

  • config : The configuration for the new channel. XML string.

Optional parameters:

  • source_password: The password for the source component. Only applicable to channels with a From File or From Database component. string.
  • destination_password: The password for the destination component. Only applicable to channels with a To File or To Database component. string.
  • salt: A value used to re-encrypt the passwords in certain component types. Useful when cloning channels between servers to prevent passwords from becoming invalid. string.
  • compact: If true return XML in compact format, value = “true”|”false” (default = “true”) boolean string.

Sample Code

-- Add a new LLP Listener -> To Translator channel with
-- the default configuration.
local Config = net.http.post{url='localhost:6543/get_default_config',
   auth={password='password', username='admin'},
   parameters={compact='true', source='LLP Listener', destination = 'To Translator'},
   live=true
}
-- Set the channel name in Config XML
XmlTreeCfg = xml.parse(Config)
XmlTreeCfg.channel.name = 'My Channel'
Config = tostring(XmlTreeCfg)
-- Create the new channel
local MyChannelCfg = net.http.post{url='localhost:6543/add_channel',
   auth={password='password', username='admin'},
   parameters={compact='true', config=Config},
   live=true
}
-- Clone a channel within the same server and give it a unique name.
local Config = net.http.post{url='localhost:6543/get_channel_config',
   auth={password='password', username='admin'},
   parameters={compact='true', name= 'My Channel'},
   live=true
}
-- Append " - clone to the channel name
XmlTreeCfg = xml.parse(Config)
XmlTreeCfg.channel.name = XmlTreeCfg.channel.name..' - clone'
Config = tostring(XmlTreeCfg)
-- Create the new channel
local MyChannelCfg = net.http.post{url='localhost:6543/add_channel',
   auth={password='password', username='admin'},
   parameters={compact='true', config=Config},
   live=true
}

For More Information

current_version [top]

Usage:

net.http.post{url='<value>/current_version’,

auth={password=<value>, username=<value>},

live=<true/false>

}

Returns a table containing version information for the Iguana server, fomatted as JSON. The JSON table has the following fields: Major, Minor, Build, and BuildExt, if the connection isn’t live then the table will be empty.

This can be used to determine if a given Iguana server has the channel API available, and to perform conditional operations with the API as it evolves over time.

Returns:

  • Version information for the Iguana server. MIME type: application/json.

Required parameters: None

Optional parameters: None

Sample Code

-- get the version information for the Iguana Server
local Version = net.http.post{url='localhost:6543/current_version',
   auth={password='password', username='admin'},
   live=true
}

if Version.Major == 5 and Version.Minor == 6 then
   -- perform an operation on the server specific to this Iguana version
end

export_project [top]

Usage:

net.http.post{url='<value>/export_project‘,

auth={password=<value>, username=<value>},

parameters={guid=<value>, [, milestone_name=<value>] [, sample_data=<value>]},

live=<true/false>

}

Retrieves a zip file containing the contents of a Translator project.

Note: You must use the correct component guid:

  • From Translator: Config.channel.from_mapper.guid
  • To Translator: Config.channel.to_mapper.guid
  • Filter: Config.channel.message_filter.translator_guid
  • From HTTP: Config.channel.from_http.guid

Do not use the channel guid Config.channel.guid

Returns:

  • The project data as a base64-encoded zip. MIME type: application/zip.

Required parameters:

  • guid: The GUID of the Translator project to export. string.

Optional parameters:

  • milestone_name: The name of the milestone to export. Default is the project’s most recent milestone. string.
  • sample_data: If false, sample data will be excluded from the project zip, value = “true”|”false” (default = “true”) boolean string.

Sample Code

-- return the project data in a base64 encoded zip format 
-- and write the base64 contents as a zip file
local Config = net.http.post{url='localhost:6543/get_channel_config',
   auth={password='password', username='admin'},
   parameters={compact='true', name='My Channel'},
   live=true
}
-- NOTE: you must use the component guid not the channel guid
local GUID = tostring(xml.parse(Config).channel.to_mapper.guid)
work
-- get the base64 project data
local Base64ZipContents = net.http.post{url='localhost:6543/export_project',
   auth={password='password', username='admin'},
   parameters={guid=GUID, sample_data=true},
   live=true
}
-- write to file (in the Iguana install directory)
local ZipFile = io.open('My Channel.zip', 'w+b')
local ZipContents = filter.base64.dec(Base64ZipContents)
ZipFile:write(ZipContents)
ZipFile:close()

get_channel_config [top]

Usage:

net.http.post{url='<value>/get_channel_config’,

auth={password=<value>, username=<value>},

parameters={name=<value> OR guid=<value> [,compact=<true/false>]},

live=<true/false>

}

Retrieves the configuration for a channel serialized as XML. This can be used with other request handlers in the API to clone channels or update existing ones. This operation requires the user to have view permission for the channel.

Note: We recommend using the guid to identify a channel, because the guid does not change when a channel is renamed.

Returns:

  • The configuration of the specified channel. MIME type: application/xml.

Required parameters:

  • name OR guid must be used to identify the channel to view.
    • name: The name of the channel to view. string.
    • guid: The GUID of the channel to view. string.

Optional parameters:

  • compact: If true return XML in compact format, value = “true”|”false” (default = “true”). boolean string.

Sample Code

-- Get the configuration of the channel named "My Channel".
local Result = net.http.post{url='localhost:6543/get_channel_config',
   auth={password='password', username='admin'},
   parameters={compact='true', name='My Channel'},
   live=true
}

For More Information

get_default_config [top]

Usage:

local Config = net.http.post{url='<value>/get_default_config’,

auth={password=<value>, username=<value>},

parameters={source=<value>, destination=<value> [,compact=<true/false>]},

live=<true/false>

}

Returns the default configuration for a channel with the specified components, serialized as XML. This can be used in conjunction with the add_channel handler to add new channels to the server with customized configurations.

Returns:

  • The default configuration for a channel with the specified components. MIME type: application/xml.

Required parameters:

  • source: The source component type for the channel. string.
    • One of:
      • LLP Listener
      • From Database
      • From File
      • From Plugin
      • From HTTPS
      • From Channel
      • From Translator
  • destination: The destination component type for the channel. string.
    • One of:
      • LLP Client
      • To Database
      • To File
      • To Plugin
      • To HTTPS
      • To Channel
      • To Translator
  • compact: If true return XML in compact format, value = “true”|”false” (default = “true”) boolean string.

Optional parameters: None

Sample Code

-- Retrieve the default configuration for a LLP Listener -> To Translator
local Config = net.http.post{url='localhost:6543/get_default_config',
   auth={password='password', username='admin'},
   parameters={compact='true', source='LLP Listener', destination = 'To Translator'},
   live=true
}

For More Information

get_server_salt [top]

Usage:

net.http.post{url='<value>/get_server_salt‘,

auth={password=<value>, username=<value>},

live=<true/false>

}

Retrieves the salt used by the Iguana server for encryption purposes. The main use for this function is to preserve password settings when cloning channels between different servers with certain component types. The component types concerned are From/To Database and From/To File.

Returns:

  • The salt used by the server for encryption. MIME type: application/plain.

Required parameters: None

Optional parameters: None

Sample Code

-- Showing how the salt can be used when cloning a channel to different server.
-- Assume that "My Channel" has at least one component with the relevant
-- password settings.

local Config = net.http.post{url='localhost:6543/get_channel_config',
   auth={password='password',username='admin'},
   parameters={compact='true', name='My Channel'},
   live=true
}
local Salt = net.http.post{url='localhost:6543/get_server_salt',
   auth={password='password',username='admin'},
   live=true
}
net.http.post{url='http://remote_iguana.com:6543/add_channel',
   auth={password='password',username='admin'},
   parameters={config=Config, salt=Salt},
   live=true
}

import_project [top]

Usage:

net.http.post{url='<value>/import_project‘,

auth={password=<value>, username=<value>},

parameters={project=<value>, guid=<value>, sample_data=<value>},

live=<true/false>

}

Sets the contents of a Translator project to the contents of a project zip file.

Note: You must use the correct component guid:

  • From Translator: Config.channel.from_mapper.guid
  • To Translator: Config.channel.to_mapper.guid
  • Filter: Config.channel.message_filter.translator_guid
  • From HTTP: Config.channel.from_http.guid

Do not use the channel guid Config.channel.guid

Returns:

  • The GUID of the Translator project into which the zip file was imported. MIME type: application/plain.

Required parameters:

  • guid:The GUID of the Translator project to import to. string.
  • project: Base64-encoded project zip file contents (matching the structure provided by export_project). MIME type: application/zip.

Optional parameters:

  • sample_data: Should be “append”, “replace”. If omitted then sample data will not be included. string.

Sample Code

-- Import a zip project file from disk into a channel component
local Config = net.http.post{url='localhost:6543/get_channel_config',
   auth={password='password', username='admin'},
   parameters={compact='true', name='My Channel'},
   live=true
}
-- get the guid for the "To Translator" in "My Channel"
local GUID = tostring(xml.parse(Config).channel.to_mapper.guid)   
-- read the project zip file, and encode the contents as base64
local ZipFile = io.open('My_Channel.zip', 'rb')
local Base64ZipContents = filter.base64.enc(ZipFile:read("*a"))
ZipFile:close()
-- import the project using the guid and base64 encoded zip contents
Base64ZipReturn = net.http.post{url='localhost:6543/import_project',
   auth={password='password', username='admin'},
   parameters={project=Base64ZipContents, guid=GUID, sample_data='replace'},
   live=true
}
-- copy a channel component using "export_project"
-- Note: This provides a convenient way to "clone" a channel
-- get the SOURCE guid for the "To Translator" in "My Other Channel"
local Config = net.http.post{url='localhost:6543/get_channel_config',
   auth={password='password', username='admin'},
   parameters={compact='true', name='adsfadsf'},
   live=true
}
local GUID = tostring(xml.parse(Config).channel.to_mapper.guid)   
-- export the project as a base64 encoded zip
Base64ZipContents = net.http.post{url='localhost:6543/export_project',
   auth={password='password', username='admin'},
   parameters={guid=GUID, sample_data=true},
   live=true
}
-- get the TARGET guid for the "To Translator" in "My Channel"
local Config = net.http.post{url='localhost:6543/get_channel_config',
   auth={password='password', username='admin'},
   parameters={compact='true', name='My Channel'},
   live=true
}
GUID = tostring(xml.parse(Config).channel.to_mapper.guid)   
-- import the project using the guid and base64 encoded zip contents
Base64ZipReturn = net.http.post{url='localhost:6543/import_project',
   auth={password='password', username='admin'},
   parameters={project=Base64ZipContents, guid=GUID, sample_data='replace'},
   live=true
}

remove_channel [top]

Usage:

net.http.post{url='<value>/remove_channel’,

auth={password=<value>, username=<value>},

parameters={name=<value> OR guid=<value> [,compact=<true/false>]},

live=<true/false>

}

Removes a channel from the Iguana server; the channel must be stopped before it can be removed. This operation requires the user to have administrator privileges.

Note: We recommend using the guid to identify a channel, because the guid does not change when a channel is renamed.

Returns:

  • The configuration of the channel that was removed. MIME type: application/xml.

Required parameters:

  • name OR guid must be used to identify the channel to remove.
    • name: The name of the channel to remove. string.
    • guid: The GUID of the channel to remove. string.

Optional parameters:

  • compact: If true return XML in compact format , value = “true”|”false” (default = “true”) boolean string.

Sample Code

-- Remove "My Channel"
local Config = net.http.post{url='localhost:6543/remove_channel',
   auth={password='password', username='admin'},
   parameters={compact='true', name='My Channel'},
   live=false
}
-- Remove "My Channel" using a GUID
 local Config = net.http.post{url='localhost:6543/get_channel_config',
   auth={password='password', username='admin'},
   parameters={compact='true', name='My Channel'},
   live=true
}
local GUID = tostring(xml.parse(Config).channel.guid)
local Config = net.http.post{url='localhost:6543/remove_channel',
   auth={password='password', username='admin'},
   parameters={compact='true', guid=GUID},
   live=true
}
-- An example where pcall() is used while removing the channel to log any errors
-- that occur.
local Success, Result, Status = pcall(net.http.post, 
   {url='localhost:6543/remove_channel',
      auth={password='password', username='admin'},
      parameters={compact='true', name='My Channel'},
      live=true
   }
)
if not Success or Status >= 400 then
   iguana.logError(Result)
end

save_project_milestone [top]

Usage:

net.http.post{url='<value>/save_project_milestone‘,

auth={password=<value>, username=<value>},

parameters={guid=<value>, milestone_name=<value>},

live=<true/false>

}

Saves a milestone for the specified Translator project.

Note: You must use the correct component guid:

  • From Translator: Config.channel.from_mapper.guid
  • To Translator: Config.channel.to_mapper.guid
  • Filter: Config.channel.message_filter.translator_guid
  • From HTTP: Config.channel.from_http.guid

Do not use the channel guid Config.channel.guid

Returns:

  • The name of the milestone that was saved. MIME type: application/plain.

Required parameters:

  • guid: The GUID of the Translator project. string.
  • milestone_name: The name of the milestone. string.

Optional parameters: None

Sample Code

-- create a milestone for a channel
-- first get the guid for the channel
local Config = net.http.post{url='localhost:6543/get_channel_config',
   auth={password='password', username='admin'},
   parameters={compact='true', name='My Channel'},
   live=true
}
local GUID = tostring(xml.parse(Config).channel.to_mapper.guid)
-- then create the milestone
local MilestoneName = net.http.post{url='localhost:6543/save_project_milestone',
   auth={password='password', username='admin'},
   parameters={guid=GUID, milestone_name='My Milestone'},
   live=true
}

status [top]

Usage:

net.http.post{url='<value>/status‘,

auth={password=<value>, username=<value>},

parameters={[action=<value>, name=<value> OR guid=<value>]},

live=<true/false>

}

Returns an XML report with information on the server itself and all the channels within it . It can also be used to start/stop channels by using the action parameter.

Note: It is not possible to retrieve information for a single channel. Information for all channels is always returned (even when the name or guid parameter is specified).

Tip: We recommend using the guid to identify a channel, because the guid does not change when a channel is renamed.

Returns:

  • The status of the server and the channels within it. MIME type: application/xml.

Required parameters: None

Optional parameters:

  • name OR guid must be used to identify the channel to apply a start/stop action to.
    • name: The name of the channel to view. string.
    • guid: The GUID of the channel to view. string.
  • action: The channel action to perform. string.
    • One of:
      • start
      • stop
      • startall (starts all channels)
      • stopall (stops all channels)

Sample Code

-- get the status for the specified server
local Status = net.http.post{url='localhost:6543/status',
   auth={password='password',username='admin'},
   live=true
}

-- parsing into an XML node tree makes it very easy to 
-- access various status information
XmlTreeStatus = xml.parse(Status)
trace(XmlTreeStatus.IguanaStatus)
local ChannelCount = XmlTreeStatus.IguanaStatus.NumberOfChannels
local Name = XmlTreeStatus.IguanaStatus:child("Channel", 2).Name

-- Construct a list of the channel names in the server.
local IguanaStatus = XmlTreeStatus.IguanaStatus
local ChannelNames = {}
for i=1, IguanaStatus:childCount("Channel") do
   table.insert(ChannelNames, IguanaStatus:child("Channel", i).Name)
end
trace(ChannelNames) -- view the channel names
-- stop and start channels
-- start/stop
local Status = net.http.post{url='localhost:6543/status',
   auth={password='password',username='admin'},
   parameters={action='start', name='My Channel'},
   -- parameters={action='stop', name='My Channel'}, -- stop: action = 'stop'
   live=true
}
-- start/stop all channels
local Status = net.http.post{url='localhost:6543/status',
   auth={password='password',username='admin'},
   parameters={action='startall', name='My Channel'},
   -- parameters={action='stopall', name='My Channel'},  -- stop: action = 'stopall'
   live=true
}

-- you can use a channel GUID instead of a channel name
local Config = net.http.post{url='localhost:6543/get_channel_config',
   auth={password='password', username='admin'},
   parameters={compact='true', name='My Channel'},
   live=true
}
local GUID = tostring(xml.parse(Config).channel.guid)

local Status = net.http.post{url='localhost:6543/status',
   auth={password='password',username='admin'},
   parameters={action='start', guid=GUID},
   live=true
}

update_channel [top]

Usage:

net.http.post{url='<value>/update_channel‘,

auth={password=<value>, username=<value>},

parameters={config=Config [, source_password=<value>] [, destination_password=<value>] [, compact=<value>]},

live=<true/false>

}

Updates the configuration of an existing channel. This can be used in conjunction with getChannelConfig{}, by first retrieving the configuration for the channel and then modifying it before being passed into this function.

This operation requires the channel to be stopped before being updated. The user must also have edit permission for the channel.

Tip: Adding or configuring From Channel source components is a bit tricky, because the From Channel settings do not store the configuration settings. The configuration for From Channel components is actually stored in the dequeue_list element within the configuration for the destination component of the channel.

See Configuring a From Channel component using the HTTP Channel API for more information.

Returns:

  • The configuration of the updated channel. MIME type: application/xml.

Required parameters:

  • config: The configuration to update the channel with. XML string.

Optional parameters:

  • source_password: The password for the source component. Only applicable to channels with a From File or From Database component. string.
  • destination_password: The password for the destination component. Only applicable to channels with a To File or To Database component. string.
  • compact: If true return XML in compact format, value = “true”|”false” (default = “true”) boolean string.

Sample Code

-- Enable the usage of the Filter in an existing channel ("My Channel")
local Config = net.http.post{url='localhost:6543/get_channel_config',
   auth={password='password',username='admin'},
   parameters={compact='true', name = 'My Channel'},
   live=true
}
-- Set use_message_filter in Config XML
XmlTreeCfg = xml.parse(Config)
XmlTreeCfg.channel.use_message_filter = 'true'
Config = tostring(XmlTreeCfg)
-- Update the channel
local MyChannelCfg = net.http.post{url='localhost:6543/update_channel',
   auth={password='password', username='admin'},
   parameters={config=Config},
   live=true
} 
trace(MyChannelCfg) -- view config to confirm the change

For More Information

  • iguanaServer.lua – Manipulate local or remote Iguana channels from the comfort of the Translator
Continue: Server API functions