Engine/RestApi

Elgg has a set of functions and classes builtin to enable a plugin to expose functionality.

First, create a function which should be accessible via the API and which will handle data; for example function your_api_function(array $params). Next, you'll need to register that function with expose_function(), which takes the following parameters:

• the name of the function to the outside world, like user.getEmail
• the handler function (function your_api_function())
• a named parameter array, where each value is an array itself containing two values:
  • the parameter name
  • a boolean indicating whether the parameter is optional or not.
• a human-readable description of the exposed function (optional)
• whether "GET" or "POST" is required (default "GET")
• whether a user authentication token is required (default true)
• whether anonymous requests are allowed (default false)

Example

This registers the function api_name as the recipient of requests to the api.name API call, which takes two parameters: an integer and an optional string.

expose_function("api.name", "api_name", array(
        "param1" => array(  // parameter name
                    'int'   // The type (int,bool,string etc)
                 ),
        "param2" => array(
                    'string',
                    true    // Optional parameter (default:false) specifying whether this parameter is optional.
                )
        ));

We then define the api_name function:

function api_test($params) {
 
	$int = $params[0];
	if (isset($params[1])) $string = $params[1];
 
	// Do some processing
        if ($error) {
            // Ensure consistent error reporting
            return ErrorResult::getInstance($message, $code, $exception);
        }
 
	return $arbitrary_result;
 
}

Admin notes

Administrators can disable this functionality via the Administrator control panel or by setting $CONFIG->disable_api = true in config.php.

Related functions

Reference/Core/expose_function