SAPI-2 - The SparkAngels API

Document Revision: 2.0X - Diffusion: External

Overview

The SparkAngels API is a Web-invocation API that allows to start a SparkAngels session from third-party Web applications.

The overall principle is that the Web application will generate two URLs, one for the Helper, the other
for the Helpee. When these URLs are opened by the client browsers, SparkAngels will be installed and started, and will initiate a SparkAngels session between the Helper (the one who views the Helpee's screen) and the Helpee (after he accepts a confirmation dialog).

SAPI-2 Description

The current version of SAPI is: Version 2.

Overall structure of SAPI messages

The SAPI messages are encoded in the URL that invokes the SparkAngels service.
The URL structure is as follows:
http://dnld0.sparkom.com/sparkangels/sangels/sparkangels.jnlp?sapi2=SAPI2_VALUE
where:
SAPI2_VALUE=(escaped SAPI-2 parameters)
where:
SAPI-2 parameters is a sequence of prmXvalueX attributes, separated by the ',' character.
The resulting sequence is escaped (encoded in application/x-www-form-urlencoded format, using the recommended encoding UTF-8). This ensures that the resulting SAPI2_VALUE can only contain '0'-'9', 'A'-'Z', 'a'-'z', '-', '_', '.','*','+','%' (attempting to use other characters will result in a 404 exception). Some parameter values are Escaped before inserting them in the sequence.
The "x" (XRef) parameter should only contain '0'-'9', 'A'-'Z', 'a'-'z', '-', '_'.

Recognized Parameters:
a: Authentication - Value is the Authentication Code provided by Sparkom to enable the use of SAPI-2
for a specific Web Application; Mandatory
v: Version - Value must be "2" (user of SparkAngel API Version 2); Mandatory
c: Control - Must be: 'S'; Mandatory
r: Role - Must be 'r' for Helper or 'e' for Helpee; Mandatory
x: Cross-Reference - Allows the association between the Helper and the Helpee and must be the same in the Helper and Helpee URLs; Mandatory
u: User Name - Allows to convey the Escaped "name" of the helper party. It is the name that will be displayed to the Helpee, in the Confirmation Dialog presented at session startup; Mandatory
s: Service Type - Must be 'c' for chat or 'p' for pmadctrl or 'v' for pmadview; Mandatory

Sample URLs:

- For the Helper named "John -,Doe":
http://dnld0.sparkom.com/sparkangels/sangels/sparkangels.jnlp?sapi2=aMyAuthCode%2Cv2%2CcS%2Crr
%2CxeZRX8_t43s%2CuJohn%2B-%252CDoe%2Csv
- For the Helpee:
http://dnld0.sparkom.com/sparkangels/sangels/sparkangels.jnlp?sapi2=aMyAuthCode%2Cv2%2CcS%2Cre
%2CxeZRX8_t43s%2CuJohn%2B-%252CDoe%2Csv

Sample JavaScript code to create it:



	var auth = MyAuthCode;

	var role = "r";			// 'r' for Helper, 'e' for Helpee

	var xref = ....;			// Some random value, containing only '0'-'9', 'A'-'Z', 'a'-'z', '-', '_'

	var helperName = escape("John -,Doe");

	var serviceType = "v";	// 'c' for Chat, 'v' for Screen Sharing (view), 'p' for Computer Sharing (control)

	var sapiValue = "a" + auth + ",v2,cS,r" + role + ",x" + xref + ",u" + helperName + ",s" + serviceType;

	var sapiUrl = "http://dnld0.sparkom.com/sparkangels/sangels/sparkangels.jnlp?sapi2=" + escape(sapiValue);

SparkAngels will start on both sides.
The Helpee will get a Confirmation dialog asking if he accept to have his screen viewed by "Helper Name". Following acceptation, the Helper and the Helpee will be in a SparkAngels session, as if they had manually started SparkAngels and exchanged the session confidential code.

xref allocation

The Cross-Reference parameter is what allows the association between the Helper and the Helpee. It is allocated by the Web Application and must be unique within the Web Application, as identified by the AUTHCODE. It needs not be unique in time, but the same xref should not be reallocated within some time interval (at least 1 hour) after the session ends.

Restarting a session

To start a new session between two clients, even if they had been in session before, a SAPI URL must be loaded again by their browsers. Starting SparkAngels from the Desktop or Startup Menu shortcuts will
not re-establish the session.

Error Handling

If the MyAuthCode is not recognized, or the SAPI2_VALUE has an invalid structure, an HTTP 404 (file not found) exception is returned.
If there are unrecognized parameters, SparkAngels will start but not setup the session. An error indication may be presented to the user.

Requirements

The SparkAngels application is a "Java Web Start" application, thus the client browser must be able to start a WebStart application automatically. This implies the following requirements:

Java version 5 must be installed and enabled on the client system and browser,
The client browser must recognize the JNLP MIME Type (application/x-java-jnlp-file) and start "javaws" for this MIME Type.

To ensure these requirements, the Web Application may provide detection code similar to SparkAngel's web code, to help the user install Java.

Conditions of use

Must obtain an AUTHCODE from Sparkom
Must not use other AUTHCODEs
Must not impair or prevent SparkAngels installation or operation
Must recognize Sparkom's ownership rights on the SparkAngels software and not misrepresent the software origin
Must not use for unlawful or unethical services
Must respect the user's intent and privacy, and not attempt to start a session without explicit and informed consent by both sides
Must accept SparkAngels CLUF