Marcus Povey <marcus@dushka.co.uk>

* API now supporting pluggable output format

git-svn-id: https://code.elgg.org/elgg/trunk@248 36083f99-b078-4883-b0ff-0f9b5a30f544

1 files changed, 140 insertions, 19 deletions

diff --git a/endpoints/rest.php b/endpoints/rest.php
index e00d27555..6f9efc1e8 100644
--- a/endpoints/rest.php
+++ b/endpoints/rest.php
@@ -11,10 +11,68 @@
 	 * @link http://elgg.org/
 	 */
 
+	
+	
+	
+	
+	/*
+
+	 Elgg API system
+A brief specification: internal only
+
+NB: this is a loose specification, and as such some holes or shortcomings may become evident in
+implementation.  Therefore, feel free to adjust as necessary, bearing in mind the goals, which 
+are unmovable ...
+
+Goals:  an extensible, two-way API that can be used to easily code secure client applications 
+on a variety of networked systems, whether web or application-based.  The results should be available, 
+at the very least, in JSON, serialised PHP, XML and CSV, but the output formats should also be 
+extensible by plugins in a documented way.  Similarly, plugins must be able to add new function calls, 
+in a similar way to how they register events or enable actions.
+
+
+
+
+
+
+On release, we will need to provide simple client libraries for PHP, .NET, C, Java and (although this 
+can hopefully be outsourced to Kevin or similar) Ruby on Rails.  Additionally, Django, vanilla Python 
+and Perl libraries would be a bonus, although not required.
+
+Brief implementation requirements:   A set of procedural functions.  If possible, the output should 
+use the existing views system, creating a new base view set for xml, json, csv and php.  That way other 
+output formats can be specified simply by changing the &view URL parameter, and added / extended by plugins.  
+(It would also allow RSS output pretty much for free for certain types of data.)  On failure, a friendly 
+message should be returned in a way that can be read by the client software.
+
+These functions should be made available in a simple api.php module within engine/lib.php, without the use of
+any external libraries.  If an external library really must be used, ensure that it has a compatible license 
+and can be used on all systems where Elgg can be installed, including Apache for Windows and Apache-compatible 
+web servers.
+
+When a plugin or core software module registers an API call, it should reference a function name, the 
+parameters it requires, and an English description of the call.  A special API call – and internal function - 
+should return a list of enabled calls, for the use of client applications and internal help pages respectively.
+
+As one application of the API is as a back-end for AJAX applications, the API endpoint should check $_SESSION 
+for logged in user information before checking for any other kind of login data.  This way the browser can 
+simply make an asynchronous callback request, allowing for many very interesting Javascript applications.
+In an ideal world, client applications should not need a special API key.  This is because an application would 
+have to install a new key for each installed Elgg site, which is not preferable, as it has a serious user 
+experience hit (before the user can use a new client software on a particular install, they have to go to 
+their account settings and obtain something that to them looks like a string of gobbledygook).  If possible, 
+all the client application should need is a valid username and password.
+
+Using a $CONFIG configuration option, site admins should be able to shut down the entire API system if 
+required, or disallow the $_SESSION authentication method.
+
+	 */
+	
+	
 	// Include required files
 	require_once('../engine/start.php');
-	global $CONFIG, $ApiEnvironment;
-	
+	global $CONFIG;
+
 	// Register the error handler
 	error_reporting(E_ALL); 
 	set_error_handler('__php_api_error_handler');
@@ -22,12 +80,18 @@
 	// Register a default exception handler
 	set_exception_handler('__php_api_exception_handler'); 
 	
+	// Check to see if the api is available
+	if ((isset($CONFIG->disable_api)) && ($CONFIG->disable_api == true))
+		throw new ConfigurationException("Sorry, API access has been disabled by the administrator.");
+	
+	
+	
+	
 	// Get parameter variables
 	$format = get_input('format', 'php');
 	$method = get_input('method');
 	$result = null;
 	
-	
 	// See if we have a session
 	/**
 	 * If we have a session then we can assume that this is being called by AJAX from 
@@ -37,7 +101,68 @@
 	 */
 	if (!isloggedin())
 	{
-		// Get api header
+		//$CONFIG->api_header = get_and_validate_api_headers(); // Get api header
+		//$CONFIG->api_user = get_api_user($CONFIG->api_header->api_key); // Pull API user details
+	
+	
+		
+		
+		
+		
+		
+		
+		
+		
+	
+	}
+	else
+	{
+		// User is logged in, just execute 
+		
+		
+		
+		
+	}
+	
+	// Finally output
+	if (!($result instanceof GenericResult))
+		throw new APIException("API Result is of an unknown type, this should never happen.");
+
+	// Output the result
+	echo output_result($result, $format);
+
+	
+	
+	
+	
+	
+	
+	
+	
+	
+	
+	
+
+	
+	
+	
+	
+	
+	
+	
+	
+	
+	
+	// See if we have a session
+	/**
+	 * If we have a session then we can assume that this is being called by AJAX from 
+	 * within an already logged on browser.
+	 * 
+	 * NB. This may be a gaping security hole, but hey ho. 
+	 */
+//	if (!isloggedin())
+//	{
+/*		// Get api header
 		$api_header = get_and_validate_api_headers();
 		$ApiEnvironment->api_header = $api_header;
 		
@@ -94,22 +219,18 @@
 		}
 		else
 			throw new SecurityException("Invalid or missing API Key.",ErrorResult::$RESULT_FAIL_APIKEY_INVALID);
-	}
-	else
-	{
-		// Set site environment
-		$ApiEnvironment->site_id = $CONFIG->site_id;
-		
-		// User is logged in, just execute 
-		if (isset($params['auth_token'])) $token = $params['auth_token'];
-		$result = execute_method($method, $params, $token);	
-	}
+	}*/
+//	else
+//	{
+//		// Set site environment
+//		$ApiEnvironment->site_id = $CONFIG->site_id;
+//		
+//		// User is logged in, just execute 
+//		if (isset($params['auth_token'])) $token = $params['auth_token'];
+//		$result = execute_method($method, $params, $token);	
+//	}
 
 
-	// Finally output
-	if (!($result instanceof GenericResult))
-		throw new APIException("API Result is of an unknown type, this should never happen.");
-		
-	output_result($result, $format);
+	
 		
 ?>
\ No newline at end of file