API responses

The framework v3.3.0+ now contains some default classes to help create standard API responses.

For instance, if you create an API endpoint in an actor like the following:

public function getEntityMeta($aEntityId=null) {
	//shortcut variable $v also in scope in our view php file.
	$v =& $this->scene;
	$this->viewToRender('results_as_json');
	$bAuthorized = $this->isAllowed('my_api', 'access');
	if ($bAuthorized) {
		if (!empty($aEntityId)) {
			$dbEntity = $this->getProp('Entity');
			try {
				$theData = $dbEntity->getEntity($aEntityId);
			}
			catch (Exception $e) {
				throw BrokenLeg::tossException($this, $e);
			}
			$v->results = APIResponse::resultsWithData($theData);
		}
	} else {
		throw BrokenLeg::toss($this, 'FORBIDDEN');
	}
}

Then because all regular exceptions that may bubble up from the model call ($dbEntity->getEntity()) get converted into BrokenLeg exceptions, those will be automatically caught by the Actor executing this method and get converted into the error potions of an APIResponse object. Also note that $v->results is set to APIResponse::resultsWithData() which ensures the data being returned is properly encapsulated by the standard API response object.

The APIResponse object definition:

{
  status: <SUCCESS|FAILURE>,
  data: <data_elements>,
  error:
  {
      cause: <cause_token>,
      message: <message>
  }
}

which of course can be modified, if desired, but that is what is provided by the framework by default. Currently defined "universal" cause_tokens which are defined in the BrokenLeg class:

• MISSING_ARGUMENT, HTTP response code: 400
• MISSING_VALUE, HTTP response code: 400
• FILE_NOT_FOUND, HTTP response code: 404
• FORBIDDEN, HTTP response code: 403
• DEFAULT, HTTP response code: 500
• DB_EXCEPTION, HTTP response code: 500
• NOT_DONE_YET, HTTP response code: 501
• DB_CONNECTION_FAILED, HTTP response code: 503
• NOT_AUTHORIZED, HTTP response code: 401
• ENTITY_NOT_FOUND, HTTP response code: 404