Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes

ApiBaseController Class Reference

ApiBaseController class. More...

Inheritance diagram for ApiBaseController:
FrontendController AppController

List of all members.

Public Member Functions

 __construct ()
 Constructor.
 __call ($method, $arguments)
 Enables calling methods for object types as /documents, /events, etc...
 getRequestMethod ()
 Return the HTTP verb of the request.
 route ()
 Any Api request has to pass from this method (see frontend app routes.php) Override FrontendController::route().
 baseUrl ($full=true)
 Return the full or partial API base url If $full is true set self::fullApiBaseUrl too and reuse it for the next time.

Public Attributes

 $uses = array()
 $components
 $ApiAuth = null

Protected Member Functions

 beforeCheckLogin ()
 Common operations that every call must do:
 checkLogin ()
 Override FrontendController::checkLogin().
 setData (array $data=array(), $merge=false)
 set self::responseData['data'] array used as output data by self::response()
 setPaging (array $paginationData)
 set self::responseData['paging'] array used by self::response() to output pagination data
 baseUrlResponse ()
 prepare response data for base api url
 setupObjectsFilter ()
 setup self::$objectsFilter from url params
 getObjects ($name=null, $filterType=null)
 GET /objects.
 addRelatedObjects (array $object, array $relations)
 Add related objects to $object The $relations is an array that contains info about the number of objects to get for each relation For example.
 postObjects ($name=null, $filterType=null)
 POST /objects.
 putObjects ($name=null, $filterType=null)
 PUT /objects/:id PUT of entire object is not allowed.
 deleteObjects ($name=null, $filterType=null)
 DELETE /objects/:id.
 saveObject (BEAppModel $beModel, array $options=array())
 Override AppController::saveObject().
 postObjectsRelations ($objectId, $relationName)
 Save relations $relationName between $objectId and related objects in $this->data.
 postObjectsChildren ($objectId)
 Save (insert or update) children ($this->data) of $objectId.
 putObjectsRelations ($objectId, $relationName=null, $relatedId=null)
 Update relation $relationName between $objectId and $relatedId objects.
 putObjectsChildren ($objectId, $childId=null)
 Update 'priority' (position relative to all children) of $childId son of $objectId.
 deleteObjectsRelations ($objectId, $relation, $relatedId)
 Delete a relation named $relation between $objectId and $relatedId.
 deleteObjectsChildren ($parentId, $childId)
 Delete from trees object $childId with $parentId as parent.
 responseChildren ($parentId, array $options=array())
 Get children of $parentId object, prepare and set response data The response is automatically paginated using self::paginationOptions self::$objectsFilter is used to populate $options['filter'].
 getObjectsChildren ($id, $childId=null)
 Load children of object $id setting data for response.
 getObjectsSections ($id)
 Load sections children of object $id setting data for response.
 getObjectsContents ($id)
 Load contents children of object $id setting data for response.
 getObjectsDescendants ($id)
 Load descendants of object $id setting data for response.
 getObjectsSiblings ($id)
 Load siblings of object $id setting data for response.
 getObjectsRelations ($id, $relation=null, $relatedId=null)
 Load relations of object $id setting data for response.
 profile ($userid=null)
 user profile end point method
 me ()
 logged user profile end point method
 getPosters ($id=null)
 GET /posters endpoint Return a poster thumbnail url of object $id or list of id's using 'id' parameter with a comma separated list of id's As 'posters' an image object is retrived using following order: 1.
 postAuth ()
 Auth POST actions.
 getAuth ()
 If user identified it responds with current access_token and the updated time to expiration.
 deleteAuth ($refreshToken)
 Revoke authentication removing refresh token If refresh token was removed successufully a 204 NO CONTENT status code returns.
 response (array $options=array())
 Build response data for client $options array permits to customize the response.
 emptyResponse ($statusCode=204)
 Send an empty response body to client Optionally it can send an HTTP status code.

Protected Attributes

 $defaultBindingLevel = 'api'
 $allowedModelBindings = array()
 $endPoints = array()
 $blacklistEndPoints = array()
 $whitelistObjectTypes = array()
 $responseData = array()
 $autoResponse = true
 $paginationOptions
 $objectsFilter = array()
 $requestMethod = null
 $allowedObjectsUrlPath
 $allowedUrlParams = array()

Detailed Description

ApiBaseController class.

Abstract Base Api Controller It must to be extended by ApiController in frontend apps

Definition at line 28 of file api_base_controller.php.


Constructor & Destructor Documentation

ApiBaseController::__construct (  ) 

Constructor.

  • Add auth component (default 'ApiAuth') to self::$components
  • Setup endpoints available:
    • Merge self::defaultEndPoints, self::endPoints
    • Add to endpoints object types whitelisted
    • remove blacklisted endpoints (self::blacklistEndPoints)

Reimplemented from AppController.

Definition at line 288 of file api_base_controller.php.


Member Function Documentation

ApiBaseController::__call ( method,
arguments 
)

Enables calling methods for object types as /documents, /events, etc...

delegating the action to self::objects()

Parameters:
string $method name of the method to be invoked
array $arguments list of arguments passed to the function
Returns:
mixed

Definition at line 321 of file api_base_controller.php.

ApiBaseController::addRelatedObjects ( array $  object,
array $  relations 
) [protected]

Add related objects to $object The $relations is an array that contains info about the number of objects to get for each relation For example.

``` array( 'attach' => 5, 'seealso' => 2, 'poster' => 1 ) ```

Parameters:
array $object the object
array $relations the relations info
Returns:
array

Definition at line 743 of file api_base_controller.php.

References FrontendController::loadRelatedObjects().

Referenced by getObjects(), and responseChildren().

ApiBaseController::baseUrl ( full = true  ) 

Return the full or partial API base url If $full is true set self::fullApiBaseUrl too and reuse it for the next time.

Parameters:
boolean $full if the url should be complete or partial
Returns:
string

Definition at line 565 of file api_base_controller.php.

Referenced by baseUrlResponse(), postObjects(), postObjectsChildren(), and postObjectsRelations().

ApiBaseController::baseUrlResponse (  )  [protected]

prepare response data for base api url

default response: show list of available endpoints with urls override in subclasses for custom response

Definition at line 583 of file api_base_controller.php.

References baseUrl().

Referenced by route().

ApiBaseController::beforeCheckLogin (  )  [protected]

Common operations that every call must do:

  • setup auth component
  • check origin
  • setup self::requestMethod to http verb used
  • normalize post data

If method is overridden in frontend ApiController remember to call parent::beforeCheckLogin()

Returns:
void

Reimplemented from AppController.

Definition at line 420 of file api_base_controller.php.

ApiBaseController::checkLogin (  )  [protected]

Override FrontendController::checkLogin().

Returns:
mixed

Reimplemented from FrontendController.

Definition at line 456 of file api_base_controller.php.

ApiBaseController::deleteAuth ( refreshToken  )  [protected]

Revoke authentication removing refresh token If refresh token was removed successufully a 204 NO CONTENT status code returns.

Parameters:
string $refreshToken the refresh token to revoke
Returns:
void

Definition at line 1803 of file api_base_controller.php.

References emptyResponse().

ApiBaseController::deleteObjects ( name = null,
filterType = null 
) [protected]

DELETE /objects/:id.

Parameters:
int|string $name
string $filterType can be a value between those defined in self::allowedObjectsUrlPath['delete']
Returns:
void

Definition at line 864 of file api_base_controller.php.

References emptyResponse().

ApiBaseController::deleteObjectsChildren ( parentId,
childId 
) [protected]

Delete from trees object $childId with $parentId as parent.

Parameters:
int $parentId the object parent id
int $childId the object child id
Returns:
void

Definition at line 1296 of file api_base_controller.php.

References emptyResponse().

ApiBaseController::deleteObjectsRelations ( objectId,
relation,
relatedId 
) [protected]

Delete a relation named $relation between $objectId and $relatedId.

Parameters:
int $objectId the object id
string $relation the relation name
int $relatedId the related id
Returns:
void

Definition at line 1269 of file api_base_controller.php.

References emptyResponse().

ApiBaseController::emptyResponse ( statusCode = 204  )  [protected]

Send an empty response body to client Optionally it can send an HTTP status code.

Parameters:
int $statusCode a status code to send to client (default 204 No Content) set it to null or other empty values to avoid to send status code
Returns:
void

Definition at line 1857 of file api_base_controller.php.

References response().

Referenced by deleteAuth(), deleteObjects(), deleteObjectsChildren(), and deleteObjectsRelations().

ApiBaseController::getAuth (  )  [protected]

If user identified it responds with current access_token and the updated time to expiration.

Returns:
void

Definition at line 1785 of file api_base_controller.php.

References setData().

ApiBaseController::getObjects ( name = null,
filterType = null 
) [protected]

GET /objects.

If $name is passed try to load an object with that id or nickname

Parameters:
int|string $name an object id or nickname
string $filterType can be a value between those defined in self::allowedObjectsUrlPath['get']
Returns:
void

Definition at line 610 of file api_base_controller.php.

References addRelatedObjects(), FrontendController::getPublication(), FrontendController::loadObj(), responseChildren(), setData(), and setupObjectsFilter().

Referenced by postObjects(), and profile().

ApiBaseController::getObjectsChildren ( id,
childId = null 
) [protected]

Load children of object $id setting data for response.

Parameters:
int $id
Returns:
void

Definition at line 1407 of file api_base_controller.php.

References responseChildren(), and setData().

Referenced by putObjectsChildren().

ApiBaseController::getObjectsContents ( id  )  [protected]

Load contents children of object $id setting data for response.

Parameters:
int $id
Returns:
void

Definition at line 1459 of file api_base_controller.php.

References responseChildren().

ApiBaseController::getObjectsDescendants ( id  )  [protected]

Load descendants of object $id setting data for response.

Parameters:
int $id
Returns:
void

Definition at line 1485 of file api_base_controller.php.

References responseChildren().

ApiBaseController::getObjectsRelations ( id,
relation = null,
relatedId = null 
) [protected]

Load relations of object $id setting data for response.

Parameters:
int $id the main object id
string $relation the relation name
int $relatedId the related object id
Returns:
void

Definition at line 1522 of file api_base_controller.php.

References FrontendController::loadRelatedObjects(), setData(), and setPaging().

Referenced by putObjectsRelations().

ApiBaseController::getObjectsSections ( id  )  [protected]

Load sections children of object $id setting data for response.

Parameters:
int $id
Returns:
void

Definition at line 1438 of file api_base_controller.php.

References responseChildren().

ApiBaseController::getObjectsSiblings ( id  )  [protected]

Load siblings of object $id setting data for response.

Parameters:
int $id
Returns:
void

Definition at line 1500 of file api_base_controller.php.

References FrontendController::getStatus(), and responseChildren().

ApiBaseController::getPosters ( id = null  )  [protected]

GET /posters endpoint Return a poster thumbnail url of object $id or list of id's using 'id' parameter with a comma separated list of id's As 'posters' an image object is retrived using following order: 1.

if object $id has a 'poster' relation return that image object 2. else if object $id is an image object type return it 3. else if object $id has an 'attach' relation with an image return that image

Possible query url paramters are:

  • 'width' the thumbnail width
  • 'height' the thumbnail height
Parameters:
int|string $id the object id or object nickname
Returns:
void

Definition at line 1640 of file api_base_controller.php.

References setData().

ApiBaseController::getRequestMethod (  ) 

Return the HTTP verb of the request.

Returns:
string

Definition at line 336 of file api_base_controller.php.

ApiBaseController::me (  )  [protected]

logged user profile end point method

Returns:
void

Definition at line 1614 of file api_base_controller.php.

References profile().

ApiBaseController::postAuth (  )  [protected]

Auth POST actions.

Depending from 'grant_type':

  • if 'grant_type' is 'password' and credentials are good then generate 'access_token' (JWT) and refresh token
  • if 'grant_type' is 'refresh_token' it expects a 'refresh_token' and if it's valid renew 'access_token'
Returns:
void

Definition at line 1725 of file api_base_controller.php.

References setData().

ApiBaseController::postObjects ( name = null,
filterType = null 
) [protected]

POST /objects.

Parameters:
int|string $name the object id or nickname
string $filterType can be a value between those defined in self::allowedObjectsUrlPath['post']
Returns:
void

Definition at line 789 of file api_base_controller.php.

References baseUrl(), getObjects(), and saveObject().

ApiBaseController::postObjectsChildren ( objectId  )  [protected]

Save (insert or update) children ($this->data) of $objectId.

If you want to save only one child $this->data should be ``` array( 'child_id' => 10, 'priority' => 1 ) ```

If you want to save children $this->data should be ``` array( array( 'child_id' => 10, 'priority' => 1 ), array(...) ) ```

See also:
ApiValidatorComponent::checkChildren() to see the right format
Parameters:
int $objectId the object id
Returns:
void

Definition at line 1107 of file api_base_controller.php.

References baseUrl(), and setData().

ApiBaseController::postObjectsRelations ( objectId,
relationName 
) [protected]

Save relations $relationName between $objectId and related objects in $this->data.

If you want to save only one relation $this->data should be ``` array( 'related_id' => 10, // required 'priority' => 1, // optional 'params' => array() // optional ) ```

If you want to save many relations $this->data should be ``` array( array( 'related_id' => 10, // required 'priority' => 1, // optional 'params' => array() // optional ), array(...) ) ```

See also:
ApiValidatorComponent::checkRelations()
Parameters:
int $objectId the main object id
string $relationName the relation name (direct or inverse)
Returns:
void

Definition at line 1003 of file api_base_controller.php.

References baseUrl(), and setData().

ApiBaseController::profile ( userid = null  )  [protected]

user profile end point method

Parameters:
int|string $userid an user id or userid
Returns:
void

Definition at line 1594 of file api_base_controller.php.

References getObjects().

Referenced by me().

ApiBaseController::putObjects ( name = null,
filterType = null 
) [protected]

PUT /objects/:id PUT of entire object is not allowed.

If you want modify an object you should use POST

Parameters:
int|string $name the object id or nickname
string $filterType can be a value between those defined in self::allowedObjectsUrlPath['put']
Returns:
void

Definition at line 843 of file api_base_controller.php.

ApiBaseController::putObjectsChildren ( objectId,
childId = null 
) [protected]

Update 'priority' (position relative to all children) of $childId son of $objectId.

$this->data should be ``` array( 'priority' => 1 ) ```

If 'priority' is not passed then a 400 is thrown $childId must already be a child of $objectId

Parameters:
int $objectId the parent object id
int $childId the child object id
Returns:
void

Definition at line 1232 of file api_base_controller.php.

References getObjectsChildren().

ApiBaseController::putObjectsRelations ( objectId,
relationName = null,
relatedId = null 
) [protected]

Update relation $relationName between $objectId and $relatedId objects.

$this->data should be ``` array( 'priority' => 1, 'params' => array() ) ```

If 'priority' or 'params' is not passed then they are set to null to update db field to NULL. Indeed PUT replaces all relation data with new one

Parameters:
int $objectId the main object id
string $relationName the relation name (direct or inverse)
int $relatedId the related object id
Returns:
void

Definition at line 1174 of file api_base_controller.php.

References getObjectsRelations().

ApiBaseController::response ( array $  options = array()  )  [protected]

Build response data for client $options array permits to customize the response.

Possible values are:

  • 'emptyBody' true to send empty body to client (default false)
  • 'statusCode' the HTTP status code you want to send to client
  • 'setBase' false to avoid to set base response metadata (default true)

self::autoResponse is set to false

Parameters:
array $options should set generic api response info
Returns:
void

Definition at line 1827 of file api_base_controller.php.

Referenced by emptyResponse(), and route().

ApiBaseController::responseChildren ( parentId,
array $  options = array() 
) [protected]

Get children of $parentId object, prepare and set response data The response is automatically paginated using self::paginationOptions self::$objectsFilter is used to populate $options['filter'].

See also:
FrontendController::loadSectionObjects()
Parameters:
int $parentId the parent id
array $options an array of options for filter results
Returns:
void

Definition at line 1332 of file api_base_controller.php.

References addRelatedObjects(), FrontendController::loadSectionObjects(), setData(), and setPaging().

Referenced by getObjects(), getObjectsChildren(), getObjectsContents(), getObjectsDescendants(), getObjectsSections(), and getObjectsSiblings().

ApiBaseController::route (  ) 

Any Api request has to pass from this method (see frontend app routes.php) Override FrontendController::route().

The method checks for valid api endpoints and call method or fallback to self::__call()

Returns:
void

Reimplemented from FrontendController.

Definition at line 528 of file api_base_controller.php.

References baseUrlResponse(), and response().

ApiBaseController::saveObject ( BEAppModel beModel,
array $  options = array() 
) [protected]

Override AppController::saveObject().

  • set default $options different from AppController::saveObject()
  • set additional data (status, user_created, user_modified, object_type_id,...)
  • check object data through ApiValidator
  • format object data through ApiFormatter
  • save object using parent::saveObject()
  • save parents in case (remove old parents and add new one)
  • save relations in case
Parameters:
BEAppModel $beModel
array $options
Returns:
void

Reimplemented from AppController.

Definition at line 904 of file api_base_controller.php.

References FrontendController::getStatus().

Referenced by postObjects().

ApiBaseController::setData ( array $  data = array(),
merge = false 
) [protected]

set self::responseData['data'] array used as output data by self::response()

Parameters:
array $data
boolean $merge true if $data has to be merged with previous set
Returns:
void

Definition at line 506 of file api_base_controller.php.

Referenced by getAuth(), getObjects(), getObjectsChildren(), getObjectsRelations(), getPosters(), postAuth(), postObjectsChildren(), postObjectsRelations(), and responseChildren().

ApiBaseController::setPaging ( array $  paginationData  )  [protected]

set self::responseData['paging'] array used by self::response() to output pagination data

Parameters:
array $paginationData
Returns:
void

Definition at line 516 of file api_base_controller.php.

Referenced by getObjectsRelations(), and responseChildren().

ApiBaseController::setupObjectsFilter (  )  [protected]

setup self::$objectsFilter from url params

Returns:
void

Definition at line 594 of file api_base_controller.php.

Referenced by getObjects().


Member Data Documentation

ApiBaseController::$allowedObjectsUrlPath [protected]
Initial value:
 array(
        'get' => array(
            'relations',
            'children',
            'contents',
            'sections',
            'descendants',
            'siblings',
            
            
        ),
        'post' => array(
            'relations',
            'children'
        ),
        'put' => array(
            'relations',
            'children'
        ),
        'delete' => array(
            'relations',
            'children'
        )
    )

Definition at line 211 of file api_base_controller.php.

ApiBaseController::$components
Initial value:
 array(
        'ResponseHandler' => array('type' => 'json'),
        'ApiFormatter',
        'ApiValidator'
    )

Reimplemented from AppController.

Definition at line 42 of file api_base_controller.php.

ApiBaseController::$paginationOptions [protected]
Initial value:
 array(
        'page' => 1,
        'pageSize' => 20,
        'maxPageSize' => 100
    )

Definition at line 160 of file api_base_controller.php.


The documentation for this class was generated from the following file:
Generated on Fri Dec 11 2015 15:29:45 by Doxygen 1.7.1  BEditaBEdita 3.7 Corylus