This is a brief summary of the technical specifications of the component technologies that comprise AIRShip. We provide more details about each technology in the appropriate pages of our Support Centre.
The AIRShip Shipping Agent (SA) is an application downloaded and installed on each computer used for shipping, synchronising and processing files. It is configured to manage a Location in the AIRShip portal to which you have access. All shipping and synchronisation between Locations is carried out by the Shipping Agents managing them.
It is a binary application, available for all common operating systems (see below), and is installed as a service, which runs permanently in the background; this ensures that it performs as reliably as the operating system on which it is being used.
Once configured, SAs poll the AIRShip portal every 300 seconds to check if there are any Workflow Tasks for them to progress. If there are, the portal will send them appropriate information, including the contact details (IP address/port number) of any other SAs with which they should connect to carry out the Tasks. They can handle multiple Tasks concurrently.
SAs can be configured as Endpoints (comparable with addresses from/to which conventional couriers collect/deliver packages) or Transit Hubs (for which there is a direct comparison with courier companies, which operate a network of transit hubs). Data is transferred direct between Endpoints and/or via Transit Hubs. Transit Hubs can be assigned to many Endpoints, acting as their intermediary (explained in more detail below).
To ship direct between Endpoints, at least one of the computers involved must be able to receive an inbound connection on port 4115. This is achieved by configuring any firewall that is in front of the computer – including Window’s own firewall if applicable – and port-forwarding port 4115 from the firewall to the computer’s private IP address). If this is not possible, a Transit Hub can be used as an intermediary (this is explained in more detail below, and in our Support Centre).
SAs establish secure communication channels with each other using RSA-2048 encryption, and send data encrypted to the AES-256 standard. They manage bandwidth dynamically, always ensuring that they are utilising only as much bandwidth as they are allowed, and sharing it out optimally across all Tasks they are managing, even as new Tasks are starting and others finishing.
SAs are responsible for monitoring any configured Watch Folders; when they detect any changes (new, edited or deleted files) they report the event to the portal, such that it can create new shipping/synchronisation Tasks for the relevant SAs to progress.
Shipping Agents can monitor as many Watch Folders as are required
SAS can be managed and their configuration settings updated remotely (a command line configuration tool available for those managing headless systems). SAs auto-upgrade when new versions are made available.
An AIRShip Location can be created as a Transit Hub, such that it can be assigned to Endpoints. The Transit Hub acts as an intermediary, providing a stepping stone for the delivery of files. The transitory files are stored encrypted on the Transit Hub, and are deleted when they have been delivered to the destination Endpoint.
Using a Transit Hub is the best way to resolve the problem of a computer on which an Endpoint is configured not being able to receive inbound connections on port 4115 (the default port via which Shipping Agents communicate). Conventionally, a Transit Hub should be assigned to any Endpoints configured on computers without fixed IP addresses. The computers on which Transit Hubs are configured are always set up to accept inbound connections on port 4115.
The following diagram illustrates how a Transit Hub works (you can view a larger version of this image as a PDF):
The Shipping Agent monitors Watch Folders for changes, which it then reports to the portal. It is able to monitor these changes using the default system-level notifications provided by OS X and Linux; however, the architecture of the Windows operating system required us to develop a mini-filter, which must be installed if you want to use AIRShip for synchronising files on computers running Windows.
The mini-filter detects new, edited or deleted files, and passes these notifications to the Shipping Agent, which then processes them.
AIRShip portals are at the centre of the AIRShip universe. We host a public portal, used by organisations large and small, and also supply private portals to those clients who prefer exclusive access (and especially if they wish to integrate AIRShip with third-party applications). Unless interacting with a portal via our API, all AIRShip-related activity is carried out by users who have logged into the portal. Users have one of three levels of permissions, which enable them to access specific functionality:
- User – create and monitor Workflows, create Cargo, and create sub-Projects;
- Company administrator – register users, create and manage all of Locations, top-level Projects, Scripts, Private Networks, Workflow Templates, and Relationships with other companies (which can be considered as organisational units in larger entities);
- System administrator – edit system-wide settings to suit, and create new language packs for localisation.
We host our portals on Amazon Web Services (AWS), installing them on servers deployed across multiple availability zones in the US East (N.Virginia) region. In addition, we use Galera clustering to ensure maximum resilience. Our servers sit behind load balancers, which manage inbound requests that are distributed across the clustered servers. We also use AWS for hosting our own Transit Hubs (these are explained in more detail in the Shipping Agent section of these Tech Specs).
Our infrastructure evolves constantly, therefore the following graphic is only representative, and contains limited components for clarity.
Our API enables seamless integration with third-party applications, such that AIRShip functionality is accessed via their interfaces. We can be confident that it works “out of the box”, because it is used by all of our portals, for the processing of all requests/responses.
It is available to clients who commission a private portal. If you are considering this option, we will be pleased to discuss your specific requirements. By way of introduction, what follows is an extract from the opening pages of our API documentation.
The AIRShip API uses the XML-RPC protocol to receive requests and provide responses. More information on the XML-RPC protocol can be found on the internet – Wikipedia provides a good founding on the subject.
Whilst the AIRShip API is implemented in PHP (as is the rest of the AIRShip portal), third-party clients can be written in any language that supports the sending of messages over network sockets using HTTPS (since the AIRShip portal will only work on HTTPS hosts). Appropriate languages include Java, Perl, PHP and Python.
URL for API Requests
The AIRShip API is contained within the code of the AIRShip portal. Given a portal URL of:
the API is available through the following URL:
It is to this URL that all API requests are directed.
Connecting to the API
The process for making an API request is quite straightforward: simply send the request as an HTTP POST request in the appropriate format, with an encoding of “application/x-www-form-urlencoded”.
Using API Sessions
Nearly all of our API methods require that a session is established (i.e. the client has logged into the portal) before they can be invoked. The only exceptions to this rule are the Login and ForgotPassword API methods. A typical API exchange is as follows:
- Send Login request;
- Receive Session ID in response (a session has been established, and is persisted automatically by the portal);
- Send List Workflows request (must contain the Session ID to authenticate/validate the request);
- Receive response … etc, and then …
- Send Logout request;
- Receive response (the session is terminated and a new session will be required for further interaction with the API).
Every Portal is configured with a default timeout of thirty minutes. Therefore, if no requests are made for a particular session within that period, the session is automatically terminated. If, subsequent to a timeout, a further request is made with the same (now-expired) Session ID, the request will be rejected with an appropriate error message in the response.
Every piece of text in AIRShip portal is defined by a “translation string”. Language-specific text for each of these translation strings can be defined in the portal, with all of the text for a specific language comprising the “language pack” for that language.
The advantage of this is that AIRShip can be localised in one of two ways:
- Language packs can be created for languages other than English;
- Language packs can be created for a private portal, incorporating custom terminology preferred by the client commissioning it.
AIRShip detects the language preferences of users browsing the portal, and displays the language pack appropriate to their locale (the default – and only language available at present – is English, but the functionality is available should a client wish to commission additional language packs for their use).