Class Api2Controller

2nd generation REST API for X2Engine.

Has the following conventions:

General:

The bodies of all requests sent and all responses received to/from this controller shall be JSON-encoded, not URL-encoded as in traditional POST (i.e. as if to mimic form submission)
HTTP Basic authentication in use. Note, this allows direct browser explorability via entering the username and API key when prompted.
The status code is to be included in the "status" property of the response, if it is not in the "success" category.
The "Content-Type" header in all responses shall be "application/json"

Model-Centric (Active Record) Actions:

If the request is successful, the returned object should not be within an envelope.
All URLs referring to operations on existing records shall end in ".json"
In responses with errors, the "errors" property is to contain the validation errors as returned from CActiveRecord.getErrors()

CComponent

CBaseController

CController

Api2Controller

Package: application\controllers
Author: Demitri Morgan <demitri@x2engine.com>
Located at x2engine/protected/controllers/Api2Controller.php

Methods summary
`public`	# `actionAppInfo( )` "Hello world" action. "Hello world" action. Prints application and network info
`public`	# `actionCount( string $_class, array $_findBy = null )` Retrieve the number of models of a specific class or matching query criteria Retrieve the number of models of a specific class or matching query criteria Parameters `$_class` `string` $_class Model name `$_findBy` `array` $_findBy Model query criteria
`public`	# `actionDropdowns( integer $_id = null )` Responds with dropdown list metadata Responds with dropdown list metadata Parameters `$_id` `integer` $_id
`public`	# `actionFieldPermissions( mixed $_class )` Returns an array of role-specific field-level permissions Returns an array of role-specific field-level permissions
`public`	# `actionFields( string $_class, string $_fieldName = null )` Access fields for a given X2Model class Access fields for a given X2Model class Parameters `$_class` `string` $_class Model name `$_fieldName` `string` $_fieldName Field name
`public`	# `actionHooks( integer $_id = null, string $_class = null )` Action for the creation of "hooks" (see `ApiHook`) Action for the creation of "hooks" (see `ApiHook`) Parameters `$_id` `integer` $_id ID of the hook. `$_class` `string` $_class Subclass of `X2Model` to which the hook pertains
`public`	# `actionModel( string $_class, integer $_id = null, array $_findBy = null )` Basic operations on an X2Engine model. Basic operations on an X2Engine model. Parameters `$_class` `string` $class `$_id` `integer` $id `$_findBy` `array` $modelInput Model parameters, i.e. if doing a lookup
`public`	# `actionModels( integer $partialSupport = 1 )` Responds with a JSON-encoded list of model classes. Responds with a JSON-encoded list of model classes. Parameters `$partialSupport` `integer` $partialSupport 1 to include partially-supported models, 0 to include only fully-supported models.
`public`	# `actionRelationships( type $_class = null, type $_id = null, type $_relatedId = null )` Action for viewing or modifying relationships on a model. Action for viewing or modifying relationships on a model. Parameters `$_class` `type` $_class `$_id` `type` $_id `$_relatedId` `type` $_relatedId
`public`	# `actionTags( string $_class = null, integer $_id = null, type $_tagName = null )` Query, add, or remove tags on a model. Query, add, or remove tags on a model. The body sent to this method in POST/PUT should be a JSON-encoded array of tag names. Parameters `$_class` `string` $_class The active record model class being tagged `$_id` `integer` $_id The ID of the active record being tagged `$_tagName` `type` $_relatedId The ID of a tag itself
`public`	# `actionTeapot( )` Hello-world error action; test for support of unconventional status code. Hello-world error action; test for support of unconventional status code.
`public`	# `actionUsers( type $_id = null )` Prints user metadata. Prints user metadata. Parameters `$_id` `type` $_id
`public`	# `actionZapierFields( type $_class, mixed $_permissionLevel = 1 )` Returns a list of fields in the format required by Zapier's custom action fields feature. Returns a list of fields in the format required by Zapier's custom action fields feature. Parameters `$_class` `type` $_class `$_permissionLevel`
`public`	# `afterAction( type $action )` Respond if a response hasn't already been sent. Respond if a response hasn't already been sent. If a response hasn't been sent yet and the action has executed fully, this method sends an empty response with the 204 status if the body has not been set, and the body itself with 200 otherwise. This eliminates the need to call `Api2Controller::send()` at the end of every action where content would be sent. Parameters `$action` `type` $action Overrides `CController::afterAction()`
`public`	# `attributesOf( CActiveRecord $model )` Returns the viewable attributes of an active record model in an array. Returns the viewable attributes of an active record model in an array. Parameters `$model` `CActiveRecord` $model
`public`	# `authFail( string $message )` Sends an authentication failure message to the client. Sends an authentication failure message to the client. Parameters `$message` `string` $message The message to include
`public type`	# `behaviors( )` Special behaviors for the controller. Special behaviors for the controller. This should be really basic/minimal. Returns `type` Overrides `CController::behaviors()`
`public`	# `fieldOptions( Fields $field )` Gets possible values for a field. Gets possible values for a field. Note, this is meant to be a stripped-down imitation of what is in `X2Model` already. I know this is code duplication, but considering Note, does not yet handle multiple choice (selecting more than one). Parameters `$field` `Fields` $field
`public`	# `filterAuthenticate( mixed $filterChain )` Sets the user for a stateless API request Sets the user for a stateless API request
`public`	# `filterAvailable( CFilterChain $filterChain )` Ends the request if the app is locked. Ends the request if the app is locked. Parameters `$filterChain` `CFilterChain` $filterChain
`public`	# `filterContentType( mixed $filterChain )` JSON-only enforcement for input data JSON-only enforcement for input data Rejects POST/PUT requests with improper content type request header.
`public`	# `filterMethods( type $filterChain )` Halts execution if the method does not match the list of acceptable methods for the action. Halts execution if the method does not match the list of acceptable methods for the action. Parameters `$filterChain` `type` $filterChain
`public`	# `filterRbac( type $filterChain )` Performs RBAC permission checks before allowing access to something. Performs RBAC permission checks before allowing access to something. This is to make permissions consistent with normal use of te app Parameters `$filterChain` `type` $filterChain
`public array`	# `filters( )` Returns the filter configurations. Returns the filter configurations. By overriding this method, child classes can specify filters to be applied to actions. This method returns an array of filter specifications. Each array element specify a single filter. For a method-based filter (called inline filter), it is specified as 'FilterName[ +\|- Action1, Action2, ...]', where the '+' ('-') operators describe which actions should be (should not be) applied with the filter. For a class-based filter, it is specified as an array like the following: array( 'FilterClass[ +\|- Action1, Action2, ...]', 'name1'=>'value1', 'name2'=>'value2', ... ) where the name-value pairs will be used to initialize the properties of the filter. Note, in order to inherit filters defined in the parent class, a child class needs to merge the parent filters with child filters using functions like array_merge(). Returns `array` a list of filter configurations. See CFilter Overrides `CController::filters()`
`public array`	# `findConditions( string $condition, mixed $validAttributes = array() )` Generates attributes from a query parameter Generates attributes from a query parameter Takes a special format of query parameter and returns an array of attributes. The parameter should be formatted as: name1value1,,name2value2[...] Parameters `$condition` `string` $condition The condition parameter `$validAttributes` Returns `array` Associative array of key=>value pairs.
`public`	# `getDataProvider( string $modelClass = null, CDbCriteria $extraCriteria = null, string $combineOp = 'AND' )` Creates a CActiveDataProvider object for search queries. Creates a CActiveDataProvider object for search queries. Parameters `$modelClass` `string` $modelClass Optional, class of CActiveRecord. If unspecified, the class of staticModel will be used. `$extraCriteria` `CDbCriteria` $extraCriteria Criteria to merge with the automatically created criteria. `$combineOp` `string` $combineOp How to combine the custom/extra criteria
`public`	# `getEnabled( )` Returns enabled Returns enabled
`public array`	# `getJpost( )` Gets POST-ed, JSON-encoded data. Gets POST-ed, JSON-encoded data. Returns `array`
`public`	# `getMaxPageSize( )`
`public X2Model`	# `getModel( )` Returns the current active record currently being operated on. Returns the current active record currently being operated on. Checks for a valid model type/ID and sets the model property. Returns `X2Model`
`public`	# `getReservedParams( )` Returns an array listing all "reserved" query parameters. Returns an array listing all "reserved" query parameters.
`public X2Model`	# `getStaticModel( )` Returns a static instance of the current effective model type. Returns a static instance of the current effective model type. Performs a check for valid model class. Returns `X2Model`
`public`	# `handleException( Exception $e )` Exception handling for the web API Exception handling for the web API Handle CHttpException instances more gracefully, and defer to the exception handler of `ResponseUtil` in all other cases. Parameters `$e` `Exception` $e
`public`	# `kludgesForActions( )` Special checks and operations to perform when working with Actions. Special checks and operations to perform when working with Actions.
`public`	# `kludgesForSearchingActions( type & $searchAttributes, CDbCriteria $criteria )` Work-arounds for querying records of the Actions class, which is special Work-arounds for querying records of the Actions class, which is special The `Actions` class is special and different from all the other `X2Model` sub-classes, hence this function was written to deal with the differences. Parameters `$searchAttributes` `type` $searchAttributes Search parameters `$criteria` `CDbCriteria` $criteria The search criteria to modify
`public`	# `log( type $message, type $level = 'info', type $category = 'application.api' )` Logs an API message. Logs an API message. Parameters `$message` `type` $message `$level` `type` $level `$category` `type` $category
`public static type`	# `methods( )` Returns an array describing acceptable methods for each API action Returns an array describing acceptable methods for each API action Each key in the returned array is a controller ID; Each value in the array is a comma-delineated list (string) of methods If a controller's ID is not in this array, it is assumed that it should accept any request method used. Returns `type`
`public`	# `send( integer $status = 200, string $message = '' )` Sends a HTTP response and logs the message that was sent. Sends a HTTP response and logs the message that was sent. Parameters `$status` `integer` $status `$message` `string` $message
`public`	# `sendEmpty( type $message = '' )` Respond with empty body and optionally log a message. Respond with empty body and optionally log a message. Parameters `$message` `type` $message
`public`	# `setModel( X2Model $model )` Sets the current working model. Sets the current working model. Parameters `$model` `X2Model` $model
`public type`	# `setModelAttributes( type $fields = array() )` Sets the current acting model with data submitted to the server. Sets the current acting model with data submitted to the server. Parameters `$fields` `type` $fields Returns `type`
`public`	# `setResponseBody( mixed $object )` Sets the body of the response Sets the body of the response Parameters `$object` `mixed` $object The object to JSON encode and include in the response

Methods inherited from CController
__construct(), accessRules(), actions(), afterRender(), beforeAction(), beforeRender(), clearPageStates(), createAbsoluteUrl(), createAction(), createActionFromMap(), createUrl(), filterAccessControl(), filterAjaxOnly(), filterPostOnly(), forward(), getAction(), getActionParams(), getCachingStack(), getClips(), getId(), getLayoutFile(), getModule(), getPageState(), getPageTitle(), getRoute(), getUniqueId(), getViewFile(), getViewPath(), init(), invalidActionParams(), isCachingStackEmpty(), loadPageStates(), missingAction(), processDynamicOutput(), processOutput(), recordCachingAction(), redirect(), refresh(), render(), renderClip(), renderDynamic(), renderDynamicInternal(), renderPartial(), renderText(), replaceDynamicOutput(), resolveViewFile(), run(), runAction(), runActionWithFilters(), savePageStates(), setAction(), setPageState(), setPageTitle()

Methods inherited from CBaseController
`beginCache(), beginClip(), beginContent(), beginWidget(), createWidget(), endCache(), endClip(), endContent(), endWidget(), renderFile(), renderInternal(), widget()`

Methods inherited from CComponent
`__call(), __get(), __isset(), __set(), __unset(), asa(), attachBehavior(), attachBehaviors(), attachEventHandler(), canGetProperty(), canSetProperty(), detachBehavior(), detachBehaviors(), detachEventHandler(), disableBehavior(), disableBehaviors(), enableBehavior(), enableBehaviors(), evaluateExpression(), getEventHandlers(), hasEvent(), hasEventHandler(), hasProperty(), raiseEvent()`

Constants summary
`boolean`	`ENABLED`	`true`	#
`integer`	`MAX_PAGE_SIZE`	`1000`	#
`string`	`FIND_DELIM`	`';'`	#
`string`	`FIND_EQUAL`	`'='`	#

Constants inherited from CController
`STATE_INPUT_NAME`

Properties inherited from CController
`$defaultAction, $layout`

Magic properties summary
`public CActiveDataProvider`	`$dataProvider`	# A data provider for performing searches via API using special underscore-prefixed query parameters: _page, _limit and _order. A data provider for performing searches via API using special underscore-prefixed query parameters: _page, _limit and _order.
`public boolean`	`$enabled`	# Returns true or false based on whether API access is enabled. Returns true or false based on whether API access is enabled.
`public array`	`$jpost`	# (read-only) JSON data posted to the server. This should be used instead of the superglobal $_POST because PHP does not natively support parsing the request body into $_POST unless it's URL-form -encoded data. (read-only) JSON data posted to the server. This should be used instead of the superglobal $_POST because PHP does not natively support parsing the request body into $_POST unless it's URL-form -encoded data.
`public integer`	`$maxPageSize`	# Maximum page size. Maximum page size.
`public X2Model`	`$model`	# Active record instance, when/where applicable Active record instance, when/where applicable
`public array`	`$reservedParams`	# Underscore-prefixed parameters used by the API Underscore-prefixed parameters used by the API
`public string`	`$responseBody`	# (write-only) The body of the response to be sent (write-only) The body of the response to be sent
`public Api2Settings`	`$settings`	# (Platinum Edition only) Advanced API settings (Platinum Edition only) Advanced API settings
`public X2Model`	`$staticModel`	# Static model instance, when/where applicable Static model instance, when/where applicable

Magic properties inherited from CController
`$action, $actionParams, $cachingStack, $clips, $id, $module, $pageTitle, $route, $uniqueId, $viewPath`

Packages

Classes

Class Api2Controller

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Overrides

Parameters

Parameters

Returns

Overrides

Parameters

Parameters

Parameters

Parameters

Returns

See

Overrides

Parameters

Returns

Parameters

Returns

Returns

Returns

Parameters

Parameters

Parameters

Returns

Parameters

Parameters

Parameters

Parameters

Returns

Parameters