WS_API - AppLogic Web Services API Application.

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

Functional Overview

• HTTP : Simple HTTP based REST API calls.
• HTTPS : Secure HTTP based REST API calls.
• VPN : HTTP requests are sent through a secure VPN tunnel.

AppLogic Web Services 'WS_API' Application Boundary Properties

The IP addresses configured in the vpn_ip, usr_ip and net_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

"WS_API" Application

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.

Operation

The WS_API can be configured to work in one or a combination of the following modes:

Using HTTP

Using HTTPS

Using vpn tunnel

Application Architecture

• one firewaled input gateways - supports HTTP and HTTPS based requests
• one VPN server - serves API requests through a secure tunnel to the VPN client on the client side
• a web server - serves REST API requests
• a centralized configuration file storage
• a centralized log - collects log and stores temporary data
• a firewalled net gateway to connect with grids
• a monitoring appliance

Configure

Provision the WS_API using the app provision wizard in the AppLogic GUI or use the app provision command in the shell, do not set any properties yet. Make sure the wizard is configured not to start the application after provisioning or use the --skipstart option if the command line is used.
app provision WS_API ws_api_instance --skipstart

Next, manage the conf volume of the application:
vol manage ws_api_instance:conf

In the data sub-directory, make sure a file called vdcs.conf exists.
cd /mnt/vol/data
ls vdcs.conf

This file consists of information necessary to access the grids that will be managed through the REST API. Open the file using the vi text editor:
vi vdcs.conf

Edit the file using the template as a reference:
vdcs
   {
   vdc controller_name : host = controller_ip or FQDN
      {
      location  = "city, state, country"
      latitude  = latitude
      longitude = longitude
      }

#  vdc controller_name : host = controller_ip or FQDN
#     {
#     location  = "city, state, country"
#     latitude  = latitude
#     longitude = longitude
#     }
   }

Simply enter the relevant information for the grids that will be accessed with the API. To add information for an additional grid, uncomment the lines (remove the #) and add the information for the second grid. More grids can be added by repeating vdc block within the vdcs {...} section. Also note that setting values for latitude and longitude is optional. Save and exit the text editor.

Next, generate a public/private key pair for ssh access to the grids configured in the vdcs.conf. To generate the key pair:
ssh-keygen -t dsa -f /mnt/vol/data/gridkey
When prompted to enter a password press enter. DO NOT ENTER A PASSWORD.
chmod 600 /mnt/vol/data/gridkey*
chown 99:99 /mnt/vol/data/gridkey*


Using the public key created above i.e. gridkey.pub create a user on each of the grids configured in vdcs.conf. Copy the public key:
cat /mnt/vol/data/gridkey.pub

On each of the grids, create an API user with this key as sshkey:
user create api@domain.com pwd=- sshkey="ssh-dsa AAA.................xyz"

After the user is created exit the volume manager. The application boundary can now be configured to work in either one of the three operating modes:

HTTP mode

The application may now be started using the app start command or by using the "Start Application" button in the GUI.

Note - This mode should be used with utmost caution. There is no security check involved in this mode and anybody can create an API request without any authentication. Also all the traffic between the client and the ws_api_instance application is in plaintext.

HTTPS mode

The application may now be started using the app start command or by using the "Start Application" button in the GUI.

The first time the application is started, a PEM formatted client key consisting of the client certificate and private key called api_client.pem and a PKCS12 formatted equivalent key for browsers called api_client.p12 is created in the ssl_keys/keys sub-directory of the conf volume. The api_client.p12 key file can be used for any browser based API access amd the api_client.pem key for any non-browser based API accesss.

To generate any additional client certificates, please follow the steps below:

• Log in to the main.api_srv component of running ws_api_instance.
• Change directory to /mnt/config/ssl_keys
• Generate a private key for a 'api' user account. openssl genrsa -out keys/api_client2_privkey.pem 2048
• Generate a certificate signing request for the CA to sign. openssl req -new -key keys/api_client2_privkey.pem -out keys/api_client2_request.csr
• Sign the CSR with our CA. openssl x509 -req -days 365 -in keys/api_client2_request.csr -CA CA/CA_cert.pem -CAkey CA/private/CA_key.pem -CAserial CA/CA_cert.srl -out keys/api_client2.cer
• cat the api_client2_a.pem and cert into one for use as a command line SSL/PEM key. cat keys/api_client2_privkey.pem keys/api_client2.cer > keys/api_client2.pem
• Export the key in a format that can be used by common web browsers. openssl pkcs12 -export -in keys/api_client2.cer -inkey keys/api_client_privkey2.pem -out keys/api_client2.p14

VPN mode

The application may now be started using the app start command or by using the "Start Application" button in the GUI.

After the application starts, the VPN server appliance generates necessary server certificates and key files if these files are not already present. Log in to the appliance and execute the security.sh script located in /appliance directory to generate the client certificates and key.
[ws_api_instance:main.in_vpn appliance]# ./security.sh generate_client
Generated client SSL cerfiticate and key file.
==============================================
These files, with CA certificate file, should be copied to VPN server into
/client/ subdirectory of data volume or fs-mounted volume.
Path to client files (client.a1c65e2bae3d0b57) should be specified in auth_path property.
Location of files:
client certificate: /mnt/fs/server/client.a1c65e2bae3d0b57.crt
client key file: /mnt/fs/server/client.a1c65e2bae3d0b57.key
CA certificate file located at /mnt/fs/server/ca.crt


The client certificate (e.g. client.xxxxxxxxxxxxxxxx.crt) and key file (e.g. client.xxxxxxxxxxxxxxxx.key) are generated in the client sub-directory and the CA certificate (ca.crt) is generated in server sub-directory of the conf volume. These may be copied into the remote VPN client appliance inside the /client/ subdirectory on the data volume or nfs-mounted volume.

Notes

Open source and 3rd party software used

Related Documents

• Web Service API Reference
• Release Notes
• A sample application
• Test Plan

Questions and Comments

-- ApoorvaKulkarni - 06 Aug 2010