Vyew Server-side API Overview

Here's an example of how to create a new Vyew Room from an HTTP call.

http://vyew.com/api?cmd=create&name=my_new_room


Each API call needs to have your API key embedded into it, as well as a unix timestamp:

http://vyew.com/api?cmd=create&name=my_new_room&key=12345678&time=1292800934


Then the final step before actually executing the HTTP call, is to add a md5 hash of the query string for authentication:

query_string="cmd=create&name=my_new_room&key=12345678&time=1292800934"
md5_hash=md5sum($query_string)

final_api_call="http://vyew.com/api/?" + query_string + "&md5=" + md5_hash


So the final api call might look like this:

http://vyew.com/api?cmd=create&name=my_new_room&key=12345678&time=1292800934
         &md5=8f049234b70bf31e428a9f7232cd067f

Getting Started

If you're not working in PHP, see OTHER LANGUAGES section below.



Step 1: Download the VyewAPI Class (PHP)

The Vyew API is called over HTTP Get and can be called from any backend language, such as Perl, PHP, etc, but we currently provide a Vyew API Wrapper Class in PHP to make calls easier to manage.



Step 2: Read the VyewAPI Class documentation

Other Languages

If you're app is written in another language, you have two options:

  • Port the VyewAPI Wrapper Class to your language - we can help you with this
  • You can directly call the Vyew API via HTTP - See the HTTP section below, but most likely you will be writing your own wrapper class similar to ours anyways, so it might be easier to port our PHP class (or parts of it).



PHP Example using the VyewAPI Class

<?php
$api_key="1234567890";
$api_secret="abcdefghijklmnop";
 
require_once('VyewAPI.php');
$vyew = new VyewAPI($api_key, $api_secret);
 
//Create a new meeting room
$res=$vyew->create('Myfile.doc Meeting');
if($res[0]!=1) die("Failed to create meeting");
$vyewBookID=$res[2];
$roomURL=$res[3];
//now you could push the user to $roomURL in another browser window...
 
//Import some content from a local file on your server (over HTTP POST)
$res=$vyew->import($roomNumber, 'post:/path/to/Myfile.doc');
 
//Or... import content from a url
$res=$vyew->import($roomNumber, 'http://mywebsite.com/path/to/Myfile.doc');
 
//Invite some other people to the meeting,
$res=$vyew->invite($roomNumber, 'myFriend@gmail.com');



Calling HTTP Directly

All API methods are called via HTTP GET requests, with the exception of the 'import' command, which can optionally use POST to send a file to be imported into a meeting. To start, each API caller must have their assigned “API Key” and a “API Secret”. Treat the 'secret' as you would any other confidential password, do not use it in such a way that others can gain access to it (eg it should not be in any open client-side language such as javascript).

How to make an API call:

1. Concatenate and url-encode all parameters into a query string, such as:

cmd=create&name=my_new_room

2. Add your API KEY, and a UNIX TIMESTAMP (seconds since Epoch time)

cmd=create&name=my_new_room&key=123456678&time=12000000000

3. Create an MD5 hash of the query string, with your API secret appended to it

md5sum( "cmd=create&name=my_new_room&key=123456678&time=12000000000" + "MY_API_SECRET")
4. Add the MD5 sum as the final parameter to the query string:
<code>cmd=create&name=my_new_room&key=123456678&time=12000000000&md5=THE_MD5_HAS_HERE

5. Call the vyew API with that full query string:

http://vyew.com/api/?cmd=create&name=my_new_room&key=123456678&time=12000000000&md5=THE_MD5_HAS_HERE

6. The response will be a string of text delimited by pipe characters (|). (Some advanced commands return JSON-ecnoded data).

Response: 1|Room Created OK
  • The first element of the response will always be a numeric success or error code
  • The second element of the response will always be a text message explaining the success or error code
  • Various calls will have different other data items after those





Simple PHP code to call API without the VyewAPI Wrapper Class

callVyewAPI() function:
  • Here is a stripped down method of calling the Vyew API from PHP. It is recommended you instead use the VyewAPI class to make API calls, but this method is left here to explain how the API works internally, and for people who wish to port it to other languages.
/**
 * Makes a remote call to the Vyew API, and returns the response
 * @param cmd {string} - command string ID
 
 * @param argsArray {array} - associative array of argument names and argument values
 * @return {array} - array of responses
 */
function callVyewAPI( $cmd, $argsArray=array() )
{
   $apikey="MY_API_KEY";
   $secret="MY_SECRET";
   $apiurl="https://vyew.com/api";
   $epoch_time=time();
 
   //--- assemble argument array into string
   $query = "cmd=$cmd"
   foreach ($argsArray as $argName=>$argValue) {
       $query .= "&" . $argName . "=" . urlencode($argValue);
   }
   $query .= "&key=". $apikey . "&time=" . $epoch_time;
 
   //--- make md5 hash of the query + secret string
   $md5 = md5($query . $secret);
   $url = $apiurl . "?" . $query . "&md5=" . $md5;
 
   //--- make simple HTTP GET request, put the server response into $response
   $response = file_get_contents($url);
 
   //--- convert "|" (pipe) delimited string to array
   $responseArray = explode("|", $response);
   return $responseArray;
}



Perl Example

Note: This code has not been tested. If you are implimenting this, please contact timh@vyew.com if you find that it works, or needs some minor debugging, so we can post a working version.

Example Usage:
# libraries we need
use LWP::Simple;
use Digest::MD5 qw(md5 md5_hex md5_base64);
 
# an associative array of arguments
%args = ('email', 'foo@foobar.com',
         'pass', 'testPass');
 
# call the API subroutine
&callVyewAPI('login', %args);
 
# definition of API subroutine
# argument 1 - string, API method to call
# argument 2 - associative array, the arguments to the API method
sub callVyewAPI
{
	$apikey="MY_API_KEY";
	$secret="MY_SECRET";
	$apiurl="https://vyew.com/api";
	$epoch_time=time();
 
	# convert the arguments into a query string
	$query = 'cmd=' . $_[0];
	foreach $arg (keys $_[1])
		$query .= '&' . $arg . '=' . $args{$arg};
 
	# generate MD5 hash
	$md5 = md5_hex($query . $secret);
 
	# build the URL for the request
	$url = $apiurl . '?' . $query . '&md5=' . $md5;
 
	# make a HTTP GET request
	$response = get($url); 
	
	# explode the response into an array and return it
	split(/|/, $response); 
}



Python Example

Note: This code has not been tested. If you are implimenting this, please contact timh@vyew.com if you find that it works, or needs some minor debugging, so we can post a working version.

Example Usage:
if __name__ == '__main__':
    response = vyewAPI("login", {"email":"my@address.com", "pw":"pass"})
vyewAPI() function:
"""
  Makes a remote call over GET/HTTPS
  See example call below on how it might be used.
  @param cmd {string} - a Command string ID
  @param args {dictionary} - argument names and values
  @return {array} - array of responses
"""
import time
import cgi
import md5
import urllib
 
def vyewAPI(cmd, args):
    apikey="MY_API_KEY"
    secret="MY_SECRET"
    apiurl="https://vyew.com/api"
    ### this may not be right, does time.time() return unix epoch time in seconds?
    epoch_time=time.time()
 
    # assemble argument array into string
    query = "cmd=%s" % cmd
    for arg in args:
        query += "&%s=%s" % (arg, cgi.escape(args[arg]))
    query += "&key=%s&time=%s" % (apikey, epoch_time)
 
    # make md5 hash of the query + secret string
    md5hash = md5.md5(query + secret).hexdigest()
    url = "%s?%s&md5=%s" % (apiurl, query, md5hash)
 
    # simple GET request, put its contents into response
    response = urllib.urlopen(url).read()
 
    # Convert pipe delimited response to array
    output = [line.split('|') for line in response]
    return output



ASP

JScript example

  • TODO

ASP.NET

C# example

VB example

  • TODO



ColdFusion

Java

Error Codes

Error Code Description
1 Success
-1 Some arguments have invalid/missing data
-3 User does not exist
-5 User already exists
-6 User is not member of specified group
-7 VyewBook/meeting/subject does not exist
-8 old ID for NSTEP, should now be -7 (subject ID doesn't exist)
-9 VyewBook not owned by group (formerly:book not owned by nstep)
-10 Bad group ID or ambiguous name
-20 Command requested has reached max usage for given API Key




Related Links:







 
api/serverside.txt · Last modified: 2010/12/19 17:38 by simadmin     Back to top