WS_API_SAMPLE - AppLogic Web Services API Sample Application.

Latest Version: 1.0.0-1 BETA

The Web Service API is only available in the AppLogic 2.9 production release and later versions.

Functional Overview

The WS_API_SAMPLE application provides an example of how to build a simple portal application that accesses the AppLogic Web Service API application i.e. WS_API. This application is provided to guide developers of portals and applications which issue Web API requests to an instance of the WS_API application running on an AppLogic grid.

AppLogic Web Services 'WS_API_SAMPLE' Application Boundary Properties

Property Name	Type	Description
`in_usr_ip`	IP	This is the IP address at which a user can access the WS_API_SAMPLE portal. This property is mandatory
`net_out_ip`	IP	This is the IP address that is used by the WS_API_SAMPLE application to issue HTTP or HTTPS based requests to the WS_API application. This property is mandatory.
`vpn_out_ip`	IP	This is the IP address that is used by the WS_API_SAMPLE application to issue HTTP based requests to the WS_API application over a secure VPN tunnel. This property is mandatory.
`netmask`	IP	Network mask for the network on which `vpn_out_ip`, `in_usr_ip` and `net_out_ip` reside. This property is mandatory.
`gateway`	IP	Address of IP gateway to be used to route traffic. This property must be specified in order to access the WS_API application. This property is mandatory.
`dns1`	IP	IP address of a DNS server for host name resolutions. This property is mandatory.
`dns2`	IP	IP address of a backup DNS server for host name resolutions. Default: `0.0.0.0`.
`api_ports`	String	Comma-separated list of ports on which WS_API_SAMPLE application can be accessed. Default: `empty`
`allowed_hosts`	String	Allowed IP address or range of IP address's in CIDR format that can access the WS_API_SAMPLE. Default: `0.0.0.0/0`; (allow all)

The IP addresses configured in the vpn_out_ip, in_usr_ip and net_out_ip properties must be IP addresses available on your AppLogic grid. You can find them, together with the netmask, gateway and dns servers on the dashboard of your grid. We are working to make it possible for AppLogic to provide these addresses automatically.

Application Resources

Resources	Min	Max	Default
CPU	0.45	72	1.05
Memory	448 MB	132 GB	1.25 GB
Bandwidth	6 Mbps	12 Gbps	1.51 G

Application Volumes

The application itself uses several volumes. They are part of the application and are already configured into the appliance instances. There are no volumes that need to be configured on the application boundary.

Volume	Size	Description
`portal`	50M	This volume is used to store the sample application's code and scripts (plus anything else that is needed by the application). This volume is assigned to the NAS appliance. By default, a populated volume called 'data' is supplied for this application to use.
`vpn_key`	65M	This volume is used to store vpn key data for the application. The client.* and the ca.crt files created by the VPN appliance in an instance of WS_API application should be stored in the client sub-directory of this volume.
`mon`	50M	This volume is used to store monitoring data for the application. There is no reason for the user to access/modify this volume; this volume is used internally by the MON appliance. By default, a volume called 'mon' is supplied to store the application monitoring data.

Operation

The WS_API_SAMPLE application, it needs to be configured to access the instance of WS_API running on an AppLogic grid. Before starting this application, start an instance of WS_API application as explained here. The WS_API_SAMPLE can then be configured as per properties that are set in the instance of WS_API application. This involves the following:

edit the portal script residing on bin sub-directory of the portal volume of the application and set the IP variable in the script to:
- set the IP variable to usr_ip to issue HTTP or HTTPS based requests to the WS_API application or to aux to issue HTTP based requests over a VPN tunnel
- edit the VDC info so that it matches the vdcs.conf on the WS_API application. E.g -

# EDIT VDC info here
<p>
<label for="location">Select Location: </label>
<select name="location">
<option value="dallas">Dallas, TX, USA</option>
<option value="sandiego">San Diego, CA, USA</option>
<option value="japan">Tokyo, Japan</option>
<option value="netherlands">Amsterdam, Netherlands</option>
</select>
</p>

The above should change to VDCs that are configured in the WS_API application. If mygrid1 and mygrid2 are two VDCs running in Dallas and San Diego respectively then above HTML code should be changed to:

# EDIT VDC info here
<p>
<label for="location">Select Location: </label>
<select name="location">
<option value="mygrid1">Dallas, TX, USA</option>
<option value="mygrid2">San Diego, CA, USA</option>
</select>
</p>

The WS_API_SAMPLE can be configured to work in one of the following modes:

Using HTTP

In this mode, the portal uses regular HTTP based interface to issue API requests to the instance of WS_API application.
E.g. curl "http://usr_ip/api/v1/app/list?vdc=mygrid1".

Using HTTPS

In this mode, the portal uses secure HTTP based interface i.e. HTTPS to issue API requests to the instance of WS_API application. For this to work, the api_client.pem key should be copied to the keys sub-directory on the portal volume of the WS_API_SAMPLE application.
E.g. curl -k -E /mnt/fs/keys/api_client.pem "https://usr_ip/api/v1/app/list?vdc=mygrid1".

Using vpn tunnel

In this mode, the portal uses regular HTTP based interface to issue API requests to the instance of WS_API application through a secure VPN tunnel. To create the tunnel, simple copy the client.xxxxxxxxxxxxxxxxxxxxxxxxx.key, client.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.crt and ca.crt generated on the server sub-directory of the vpn_key volume of the instance of WS_API application to the client sub-directory of the vpn_key volume of the WS_API_SAMPLE application. A secure tunnel is created once the out_vpn component is started.
E.g. curl "http://aux/api/v1/app/list?vdc=mygrid1".

To access the portal through a web browser, point the browser to http://in_usr_ip/api/portal

Application Architecture

AppLogic Web Services 'WS_API_SAMPLE' application infrastructure is show below:

It has the following components:

one firewaled input gateway - supports HTTP and HTTPS based access to the portal
one VPN client - issues API requests through a secure tunnel to the VPN Server in the WS_API application
one firewalled net gateway - issues HTTP and HTTPS based API requests to the usr_ip of the WS_API application
a web server - runs the sample portal
a linux appliance - to issue command line based requests
a centralized configuration file storage

Notes

Open source and 3rd party software used

The following open source 3rd party software is installed on the portal volume.

Software	Version	Modified	License	Notes
JSON	2.15	No	Artistic	N/A
IPC-Run	0.82	No	Artistic	N/A
XML-Simple	1.40	No	Artistic	N/A
Sort-Naturally	1.02	No	Artistic	N/A