Web services sample code

Introduction

The web services API requires a set of information that is used for authorisation purposes; your username, a password and the cloud ID for your cloud region are required.

When invoking an outbound service, the username you supply will be your cloud username and the password will be the one that is associated with the outbound service. For the other web services commands, your username will be your cloud username and the password will be your cloud password.

The samples

The samples are provided in the ws_samples directory of your package. In this directory you will find the following files:

• ws_connect.py, connect to the cloud
• ws_command.py, run a web-services command
• list_files.py, list your cloud media files
• delete_file.py, delete a cloud media file
• download_file.py, download a cloud media file
• upload_file.py, upload a local media file to the cloud
• rename_file.py, rename a cloud media file
• invoke_outbound_service.py, invoke an outbound service
• get_application_instance_result.py, get the result of an application run
• wakeup_call.py, a wakeup call sample
• wakeup_call.cfg, the wakeup call sample configuration file
• reserve_large_conference.py, reserve a large conference on the cloud

ws_connect

There is an interface provided at cloud.aculab.com:8443 for programmatic access to the cloud filestore, and there is an interface at ws-x-y-z.aculab.com:443 for invoking outbound services or reserving large conferences (where x-y-z is the cloud region).

This file shows how to create a connection to the cloud using Python’s httplib module. For authentication we need to supply a username and a password. For many operations the username is made up of two parts, separated by a ‘/’.

For file operations, connect to cloud.aculab.com with username in the format cloud_region/cloud_username, for example 0-2-0/user.name@domain.com. The password is your cloud password.

For outbound service invocation, connect to ws-x-y-z.aculab.com with the username in the format cloud_username/outbound_service_name, for example user.name@domain.com/wakeup_call. The password is the outbound service password.

For reserving large conferences, connect to ws-x-y-z.aculab.com, username is simply your cloud username and the password is your cloud password.

ws_command

This file simply runs a web-services command and returns the response. The type of the web services command and the page depends on the operation.

For listing your media files on the cloud, the type is GET and the page is /.

For deleting a file from the cloud the type is DELETE and the page is /index?filename=file.

For downloading a file from the cloud the type is GET and the page is /index?filename=file.

For uploading a file to the cloud the type is PUT and the page is /index?filename=file.

For renaming a file on the cloud the type is PUT and the page is /index?movefrom=file&moveto=file.

For invoking an outbound service on the cloud the type is POST and the page is /makecall?args=arguments.

For reserving a large conference on the cloud the type is POST and the page is /reserve?room=name&parties=number&start=date&duration=minutes.

The file samples

These samples will each run one of the file operations. They prompt for some basic authentication and configuration information and then connect and run the web-services command. The result is displayed.

For these samples it is important that you also read the section about media files which describes some of the effects of Eventual Consistency.

The invoke outbound service sample

This sample application will ask for the name of the outbound service you want to invoke. This service will already have been registered on the Cloud Web Portal under the Outbound Services page.

When registering one of the outbound samples provided, you will have to supply a validated caller ID in the Application parameters box. You can create a validated caller ID by logging into your Aculab Cloud account on the Cloud Web Portal and going to Caller ID under the Manage tab. What you enter in the Application parameters box will be passed to the application that is started when the service is invoked. It will be passed to the application’s main function via the application_parameters argument. Some of the outbound samples also require an extra channel.

For more information on making outbound calls please read the online documentation.

After entering the name of the outbound service you want to invoke, you will be asked to enter the outbound service parameters. What you need to enter here will depend on the application that will be started as a result of invoking the service, the string will be passed to the application’s main function via the outbound_parameters argument.

You will then be asked how many instances of the service you want to invoke. Typically, if the application registered to this service is going to ring a PSTN number, you would enter 1.

You will then be asked to enter the cloud region. The could region should be entered as the Cloud ID. For example, 0-2-0 is the ID for the Europe and 1-2-0 is the ID for USA-East.

Next is your Aculab Cloud username for the region you have chosen.

Finally you will be asked for the password that you assigned to the outbound service you want to invoke. This is not necessarily the same as your Aculab Cloud password.

This sample will then attempt to invoke the outbound service.

For more information on invoking outbound services please read the online documentation.

Once the application has finished running, the sample will print a list of application instance IDs (one for each instance you started). These IDs are unique to each application instance and can be used to gather more information about each application run. The sample described below shows how to use these application instance IDs.

The get application instance result sample

This sample will use the application instance IDs returned by the sample described above to get more information about each application run.

The sample will first ask for a list of the application instance IDs to query. This will be given as a string of IDs with a ; as the delimiter.

Then you will be asked for the cloud region and you should enter an ID as described for the previous sample.

Next you will be asked for your Aculab Cloud username.

And finally you will be asked to enter your Aculab Cloud password. This is not necessarily the same as the outbound service password that you entered for the previous sample.

The application will print the sart time and duration for each instance you are querying. But other information is also available.

For more information on using this API please read the online documentation.

The UAS monitor sample

This sample connects to your UAS rather than to the cloud. It shows how to poll the UAS for its cloud connection statistics. These are simple statistics on the responsiveness of the UAS cloud connections. The responsiveness is measured as the round trip time in seconds taken for a message between the UAS and the cloud. Recorded are the Maximum, Minimum and Average time measured in seconds.

A guideline on interpreting the statistics is as follows:

• Minimum: less than 1 is good, 1 to 2 is OK, more than 2 is bad.
• Maximum: less than 5 is good, 5 to 10 OK, more than 10 is bad.
• Average: less than 2 is good, 2 to 4 is OK, more than 4 is bad.

The reserve large conference sample

The sample will ask for the necessary information and attempt to reserve a conference room. It also shows functions for doing the other web services tasks for large conference roooms, but these are not run automatically.

When making a rservation for a large conference you will provide a name for the conference. You are essentially reserving a conference room and the room requires a name. You will also be providing the maximum number of participants in the conference; the time at which the conference will start; and the duration of the conference.

The conference room will exist for the duration of the reservation, it will not exist before or after the reservation period. Some or all of the parties can join and leave the conference several times during the reservation period. Once the reservation period has expired, the room will no longer exist and any parties still in the conference will be dropped.

Once a reservation for a given conference room name has been made, that name cannot be used for another reservation (even if the reservation times do not overlap) unless the previous reservation is first removed or conference has finished.

The interface provides the following functionality:

• reserve a conference room
• extend the duration of a reservation
• remove a reservation
• return a list of all your reservation tokens
• return reservation info

reservation rules & constraints

• the room name:

  The conference room name will consist of alphanumeric characters only, and will be unique. A reservation request that provides a room name that is still in use will fail. A room name is deemed still in use if the reservation has not been removed and the conference has not finished.

• the number of parties:

  The number of parties will be an integer that is more than 20 and not more than 400.

• the conference start time:

  The conference start time will be given in Coordinated Universal Time (UTC) and be in the format YYYY-MM-DD-HH-MM (year-month-day-hour-minute, no seconds), where each field will consist of digits only, e.g, 2011-10-12-13-30. A reservation can be made at most 24 hours before the start of the conference. A reservation must be made at least five minutes before the conference start.

• conference duration:

  The duration will be an integer representing minutes and will not be less than 15 or more than 480. The duration of a reservation can be extended. This can be done before the conference starts, or while the conference is running. However, the duration cannot be extended if the conference is within five minutes of finishing. The extension will be given as an integer representing the number of minutes to add to the duration, it must be not less than 15 and not more than 60. The additional duration must not take the total duration beyond 480 minutes.

• failure cases:

  A reservation will fail if:

  The room name contains invalid characters. The number of parties is less than 21 or greater than 400. The duration is less than 15 or greater then 480 The start time is less than 5 minutes away or more than 24 hours away. A reservation with the same name already exists, it has not been cancelled and the conference hasn’t finished.

  A duration modification will fail if:

  The reservation token is not valid. The given duration is not within the specified range. The given duration plus the existing duration takes the total beyond the maximum allowed. The reservation being modified has been removed. The conference has already finished. The modification is being done within five minutes of the end of the conference.

  A remove request will fail if:

  The reservation token is not valid. The removal is requested within five minutes of the conference starting.

Function returns

Function returns will be in JSON format and will be a dictionary containing a status and a result:

{
    'status' : 'true' or 'false',
    'result' : result
}

If status is false, then an error has occurred and result will be a text desctiption of the error. If status is true, then the function has succeeded and result will be the expected return.

reserve a room

To reserve a room you need to provide the room name, the number of parties, the conference start time and the conference duration. A successful reservation will return a reservation token, this is a unique token that identifies your reservation. You will need it if you wish to remove, modify or retrieve information about your reservation.

The URI is in the format:

``https://ws-a-b-c.aculab.com/reserve?room=confRoomName&parties=numberOfParties&start=confStartTime&duration=confDuration``

extend the duration

To extend the duration of a reservation you need to provide the number of minutes by which to extend the duration and the reservation token. If successful, this command will return the new total duration of the reservation.

The URI is in the format:

``https://ws-a-b-c.aculab.com/modify?token=reservationToken&duration=addDuration``

remove a reservation

To remove a reservation you need to provide the reservation token. If successful, this command will return the name of the conference room that was removed.

The URI is in the format:

``https://ws-a-b-c.aculab.com/remove?token=reservationToken``

listing the tokens

To list all your reservation tokens the URI is:

``https://ws-a-b-c.aculab.com/list``

This command will return a JSON format list off all your reservation tokens in the format:

[
    token1,
    token2,
    token3
]

retrieving reservation information

To retrieve the information for a given reservation you need to provide the reservation token.

The URI is in the format:

``https://ws-a-b-c.aculab.com/info?token=reservationToken``

If successful, this command will return a JSON format list of reservation information in the format:

[
    confRoomName,
    numberOfParties,
    confStartTime,
    confDuration,
    isFinished
]

A note on isFinished:

When a conference has finished, the reservation information will remain available for at least another 24 hours. After this, the reservation will be removed from the database. isFinished will be ‘true’ if the conference has finished.