Siphon API Documentation

The siphon api consists of four functions: get, set, signup, and forgot. The request data is sent via a combination of url query string variables and json encoded post data.

The Request URL Query String

The request url always contains the following query string variables:

• type
  The function type. Either get, set, signup, or forgot.
• email
  The email address of the user. This value may be blank.
• password
  The password of the user. This value may be blank.
• rand
  A random value to prevent request caching.

The Response

The response is always a json encoded string. The decoded json object always contains the following attributes:

• retval
  The return value from the function. The return value is zero on success, non-zero on failure.
• alert_message
  The alert_message contains a string value that will be displayed to the user in a popup window. This value can be blank.
• status_message
  The status_message contains a string value that will be displayed to the user in the status bar of the main siphon window. This value can be blank.

The Signup Function

The signup function is the function used to create a new user account. When the type query string variable is set to signup, the email and password variables should be used to signup the user. On success, set retval to zero, on failure, set retval to a non-zero value (generally one).

The Get Function

The get function is the function used to get the currently saved addon list. On success the response should include an extra attribute, addons.

The addons attribute is an object containing the key value pairs of each saved addon. The key is the addon id and the value is another object containing the required information for that addon. The minimum required information for each addon is id, name, minAppVersion, maxAppVersion, and version. See below for an example of a get response:

	{
		"retval": 0,
		"alert_message": null,
		"status_message": "Get Function Succeeded!",
		"addons": {
			"firebug@software.joehewitt.com": {
				"id": "firebug@software.joehewitt.com",
				"name": "Firebug",
				"minAppVersion": "3.5",
				"maxAppVersion": "3.6.*",
				"version": "1.5.4"
			},

			"{8f8fe09b-0bd3-4470-bc1b-8cad42b8203a}": {
				"id": "{8f8fe09b-0bd3-4470-bc1b-8cad42b8203a}",
				"name": "Live HTTP headers",
				"minAppVersion": "0.8",
				"maxAppVersion": "3.6.*",
				"version": "0.16"
			}
		}
	}
	

The Set Function

The set function is the function used to save the addon list. The addon list will be a json encoded string in the post body of the request. The format will be an object of key value pairs of each addon to save. The format is the same as that of the addon attribute of the get response though may include more attributes than just the required id, name, minAppVersion, maxAppVersion, and version. The new addon list sent by the set function MUST replace the existing addon list for that user. Once the set function is called the addon list returned in the get response should match the addon list sent by the originating set response. This is, of course, until another set request is made.

The Forgot Function

The forgot function is the function used if the user forgot his or her password. There is no specified way to handle this, it is left up to the developer to come up with a way to handle a forgotten password. The Siphon Server sends an email to the user with instructions on how to reset their password and alerts them of this email using the "alert_message" response variable.