Class ApiBaseController

ApiBaseController class

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

Controller

AppController

FrontendController

ApiBaseController

Abstract
Located at controllers/api_base_controller.php

Methods summary

`public`	# `__construct( )` Constructor 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) Overrides `AppController::__construct`
`public mixed`	# `__call( string $method, array $arguments )` Enables calling methods for object types as /documents, /events, etc... delegating the action to self::objects() Enables calling methods for object types as /documents, /events, etc... delegating the action to self::objects() Parameters `$method` name of the method to be invoked `$arguments` list of arguments passed to the function Returns mixed
`public string`	# `getRequestMethod( )` Return the HTTP verb of the request Return the HTTP verb of the request Returns string
`private array`	# `handleInputData( )` Normalize POST/PUT data Normalize POST/PUT data This function searches for POST/PUT data in the global var $_POST and in 'php://input' alias file Some Javascript XHR wrappers POSTs, PUTs data are passed through 'php://input' If CONTENT_TYPE in request headers is 'application/x-www-form-urlencoded' then it parses string else it tries to json encode string Returns array
`private`	# `setupPagination( )` Setup the pagination options self:paginationOptions Merging default with query url params Setup the pagination options self:paginationOptions Merging default with query url params
`protected`	# `beforeCheckLogin( )` Common operations that every call must do: 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() Overrides `AppController::beforeCheckLogin`
`protected mixed`	# `checkLogin( )` Override FrontendController::checkLogin() Override FrontendController::checkLogin() Returns mixed Overrides `FrontendController::checkLogin`
`protected mixed`	# `checkPublicationPermissions( )` Override FrontendController::checkPublicationPermissions() Override FrontendController::checkPublicationPermissions() Return true if the publication is authorized for user Return null if client is trying to authenticate via `POST /auth` Returns mixed Throws `BeditaUnauthorizedException` `BeditaForbiddenException` Overrides `FrontendController::checkPublicationPermissions`
`private`	# `setupAuthComponent( )` Setup component used for authentication: Setup component used for authentication: check configuration (api.auth.component) to see if adhoc component should be used and assign it to self::$ApiAuth replace self::BeAuth with self::ApiAuth to work properly in FrontendController. BeAuthComponent is not used in API context. JWT is usually used instead via ApiAuthComponent
`private`	# `setupValidatorComponent( )` Setup component used for validation: Setup component used for validation: check configuration (api.validator.component) to see if adhoc component should be used and assign it to self::$ApiValidator
`private`	# `setupFormatterComponent( )` Setup component used for authentication: Setup component used for authentication: check configuration (api.formatter.component) to see if adhoc component should be used and assign it to self::$ApiFormatter
`private`	# `setBaseResponse( )` Set common meta data for response Meta data are: - url - params - api Set common meta data for response Meta data are: - url - params - api
`protected`	# `setData( array $data = array(), boolean $merge = false )` set self::responseData['data'] array used as output data by self::response() set self::responseData['data'] array used as output data by self::response() Parameters `$data` `$merge` true if $data has to be merged with previous set
`protected`	# `setPaging( array $paginationData )` set self::responseData['paging'] array used by self::response() to output pagination data set self::responseData['paging'] array used by self::response() to output pagination data Parameters `$paginationData`
`public`	# `route( )` Any Api request has to pass from this method (see frontend app routes.php) Override FrontendController::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() Throws BeditaBadRequestException, BeditaNotFoundException Overrides `FrontendController::route`
`public string`	# `baseUrl( boolean $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 Return the full or partial API base url If $full is true set self::fullApiBaseUrl too and reuse it for the next time Parameters `$full` if the url should be complete or partial Returns string
`protected`	# `baseUrlResponse( )` prepare response data for base api url prepare response data for base api url default response: show list of available endpoints with urls override in subclasses for custom response
`protected`	# `setupObjectsFilter( )` setup self::$objectsFilter from url params setup self::$objectsFilter from url params
`protected`	# `getObjects( integer\|string $name = null, string $filterType = null )` GET /objects GET /objects If $name is passed try to load an object with that id or nickname Parameters `$name` an object id or nickname `$filterType` can be a value between those defined in self::allowedObjectsUrlPath['get']
`protected array`	# `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 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 `$object` the object `$relations` the relations info Returns array
`private`	# `routeObjectsFilterType( integer $id, string $filterType )` Route calls made by /objects endpoint using $filterType and request method self::requestMethod Route calls made by /objects endpoint using $filterType and request method self::requestMethod Parameters `$id` `$filterType` See self:objects() for param description
`protected`	# `postObjects( integer\|string $name = null, string $filterType = null )` POST /objects POST /objects Parameters `$name` the object id or nickname `$filterType` can be a value between those defined in self::allowedObjectsUrlPath['post']
`protected`	# `putObjects( integer\|string $name = null, string $filterType = null )` PUT /objects/:id PUT of entire object is not allowed. If you want modify an object you should use POST PUT /objects/:id PUT of entire object is not allowed. If you want modify an object you should use POST Parameters `$name` the object id or nickname `$filterType` can be a value between those defined in self::allowedObjectsUrlPath['put']
`protected`	# `deleteObjects( integer\|string $name = null, string $filterType = null )` DELETE /objects/:id DELETE /objects/:id Parameters `$name` `$filterType` can be a value between those defined in self::allowedObjectsUrlPath['delete'] Overrides `AppController::deleteObjects`
`protected`	# `saveObject( BEAppModel $beModel, array $options = array() )` Override AppController::saveObject() 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 `$beModel` `$options` Overrides `AppController::saveObject`
`protected`	# `postObjectsRelations( integer $objectId, string $relationName )` Save relations $relationName between $objectId and related objects in $this->data 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(...) ) Parameters `$objectId` the main object id `$relationName` the relation name (direct or inverse) See ApiValidatorComponent::checkRelations()
`protected`	# `postObjectsChildren( integer $objectId )` Save (insert or update) children ($this->data) of $objectId 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(...) ) Parameters `$objectId` the object id See ApiValidatorComponent::checkChildren() to see the right format
`protected`	# `putObjectsRelations( integer $objectId, string $relationName = null, integer $relatedId = null )` Update relation $relationName between $objectId and $relatedId objects 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 `$objectId` the main object id `$relationName` the relation name (direct or inverse) `$relatedId` the related object id
`protected`	# `putObjectsChildren( integer $objectId, integer $childId = null )` Update 'priority' (position relative to all children) of $childId son of $objectId 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 `$objectId` the parent object id `$childId` the child object id
`protected`	# `deleteObjectsRelations( integer $objectId, string $relation, integer $relatedId )` Delete a relation named $relation between $objectId and $relatedId Delete a relation named $relation between $objectId and $relatedId Parameters `$objectId` the object id `$relation` the relation name `$relatedId` the related id
`protected`	# `deleteObjectsChildren( integer $parentId, integer $childId )` Delete from trees object $childId with $parentId as parent Delete from trees object $childId with $parentId as parent Parameters `$parentId` the object parent id `$childId` the object child id
`protected array`	# `forbiddenChildren( integer $parentId, array $user = array() )` Get list of parent children with access restricted to $user Get list of parent children with access restricted to $user Parameters `$parentId` the parent id `$user` array with user data, empty if no user is logged Returns array list of forbidden object ids, may be empty
`protected`	# `responseChildren( integer $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'] 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'] Parameters `$parentId` the parent id `$options` an array of options for filter results See FrontendController::loadSectionObjects()
`protected`	# `getObjectsChildren( integer $id, $childId = null )` Load children of object $id setting data for response Load children of object $id setting data for response Parameters `$id` `$childId`
`protected`	# `getObjectsSections( integer $id )` Load sections children of object $id setting data for response Load sections children of object $id setting data for response Parameters `$id`
`protected`	# `getObjectsContents( integer $id )` Load contents children of object $id setting data for response Load contents children of object $id setting data for response Parameters `$id`
`protected`	# `getObjectsDescendants( integer $id )` Load descendants of object $id setting data for response Load descendants of object $id setting data for response Parameters `$id`
`protected`	# `getObjectsSiblings( integer $id )` Load siblings of object $id setting data for response Load siblings of object $id setting data for response Parameters `$id`
`protected`	# `getObjectsRelations( integer $id, string $relation = null, integer $relatedId = null )` Load relations of object $id setting data for response Load relations of object $id setting data for response Parameters `$id` the main object id `$relation` the relation name `$relatedId` the related object id
`protected`	# `profile( integer\|string $userid = null )` user profile end point method user profile end point method Parameters `$userid` an user id or userid
`protected`	# `me( )` logged user profile end point method logged user profile end point method
`protected`	# `getPosters( integer\|string $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. 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 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 `$id` the object id or object nickname
`private thumb`	# `posterThumbConf( )` Returns thumbnail configuration array from URL and general configuration (used in /posters) Returns thumbnail configuration array from URL and general configuration (used in /posters) Returns thumb conf array
`private poster`	# `posterData( integer $id, array $thumbConf = array() )` Returns poster data for a single object (used in /posters) Returns poster data for a single object (used in /posters) Parameters `$id` `$thumbConf` Returns poster data array
`protected`	# `postAuth( )` 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' 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'
`protected`	# `getAuth( )` If user identified it responds with current access_token and the updated time to expiration If user identified it responds with current access_token and the updated time to expiration
`protected`	# `deleteAuth( string $refreshToken )` Revoke authentication removing refresh token If refresh token was removed successufully a 204 NO CONTENT status code returns Revoke authentication removing refresh token If refresh token was removed successufully a 204 NO CONTENT status code returns Parameters `$refreshToken` the refresh token to revoke
`protected`	# `postFiles( string $objectType = null, string $fileName = null )` Upload a file. Respond with an upload_token that it must be used to link a new object to the uploaded file. Upload a file. Respond with an upload_token that it must be used to link a new object to the uploaded file. Parameters `$objectType` The corresponding object type `$fileName` The file name
`protected`	# `response( array $options = array() )` 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) 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 `$options` should set generic api response info
`protected`	# `emptyResponse( integer $statusCode = 204 )` Send an empty response body to client Optionally it can send an HTTP status code Send an empty response body to client Optionally it can send an HTTP status code Parameters `$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
`private boolean`	# `checkOrigin( )` Checks if an origin is allowed. Allowed origins are set in `$conf['api']['allowedOrigins']`. Use `` to allow any origin. Use `http://.example.com` to allow any third-level subdomain, use `http://*.example.com` to allow any subdomain, sub-subdomain, ... Checks if an origin is allowed. Allowed origins are set in `$conf['api']['allowedOrigins']`. Use `` to allow any origin. Use `http://.example.com` to allow any third-level subdomain, use `http://*.example.com` to allow any subdomain, sub-subdomain, ... Returns boolean

Methods inherited from FrontendController

accessDenied(), buildRssItem(), captchaImage(), category(), checkPubblicationDate(), clearObjectCacheArray(), content(), delete(), download(), excludeRelations(), georss(), georssatom(), getParentsObject(), getPath(), getPublication(), getRelatedCacheExpiration(), getSectionCacheExpiration(), getStatus(), handleExceptions(), hashjob(), homePage(), initAttributes(), isLogged(), json(), kml(), lang(), loadAndSetObj(), loadAndSetObjByNick(), loadAndSetSectionObjects(), loadAndSetSectionObjectsByNick(), loadAnnotations(), loadArchiveTree(), loadObj(), loadObjByNick(), loadObjectsByCategory(), loadObjectsByTag(), loadPublications(), loadRelatedObjects(), loadSectionObjects(), loadSectionObjectsByNick(), loadSectionsLevels(), loadSectionsTree(), loadTags(), login(), logout(), manifestAppcache(), printme(), publicationDisabled(), rss(), save(), saveComment(), search(), section(), setCanonicalPath(), setPublicationDateFilter(), setupLocale(), showDraft(), sitemap(), sitemapXml(), subscribe(), tag(), treeChildrenCache(), xml(), xmlobject()

Methods inherited from AppController

afterFilter(), beditaAfterFilter(), beditaBeforeFilter(), beditaBeforeRender(), beforeFilter(), beforeRender(), checkObjectWritePermission(), currentController(), eventError(), eventInfo(), eventLog(), eventWarn(), forward(), handleError(), idFromNicknameCache(), loadModelByObjectTypeId(), loadModelByType(), modelBindings(), objectRelationArray(), objectTypeCache(), objectTypeIdCache(), prepareRelationsToSave(), setObjectBindings(), setResult(), setupAnnotations(), setup_args(), startProfiler(), stopProfiler(), updateHistory(), usedUrl(), userErrorMessage(), userInfoMessage(), userWarnMessage(), viewRevision()

Constants summary

Constants inherited from FrontendController

UNAUTHORIZED, UNLOGGED

Constants inherited from AppController

ERROR, OK, VIEW_FWD

Properties summary

`public array`	`$uses` The Models used The Models used	# `array()`
`public array`	`$components` The Components used The Components used	# `array( 'ResponseHandler' => array('type' => 'json'), 'ApiFormatter', 'ApiValidator', 'ApiUpload' )`
`public Object`	`$ApiAuth` Contain the instance of API auth component used Normally it corresponds to ApiAuthComponent but it can contain another auth component To do it a custom component, named for example 'MyAuth', has to be activated via conf Contain the instance of API auth component used Normally it corresponds to ApiAuthComponent but it can contain another auth component To do it a custom component, named for example 'MyAuth', has to be activated via conf $config['api'] = array( 'baseUrl' => '/api', 'auth' => array( 'component' => 'MyAuth' ), ... ); Note that the custom auth component should implements ApiAuthInterface	# `null`
`private array`	`$defaultEndPoints` The default endpoints The default endpoints	# `array('objects', 'auth', 'me', 'posters', 'files')`
`protected string`	`$defaultBindingLevel` The default binding level The default binding level See FrontendController::defaultBindingLevel	# `'api'`
`protected array`	`$allowedModelBindings` Allowed model bindings Used to get more or less fields and associations through GET /objects param 'binding' By default no one is permit but it is overridable in ApiController Allowed model bindings Used to get more or less fields and associations through GET /objects param 'binding' By default no one is permit but it is overridable in ApiController Example: protected $allowedModelBindings = array('default', 'frontend', 'minimum'); and call GET /objects/:name?binding=minimum	# `array()`
`protected array`	`$endPoints` Other endpoints specified in the frontend app They will be merged with self::defaultEndPoints() Other endpoints specified in the frontend app They will be merged with self::defaultEndPoints()	# `array()`
`protected array`	`$blacklistEndPoints` Endpoints blacklisted Useful for blacklisting self::defaultEndPoints Endpoints blacklisted Useful for blacklisting self::defaultEndPoints	# `array()`
`protected array`	`$whitelistObjectTypes` White list of object types that have to be mapped to endpoints For example setting White list of object types that have to be mapped to endpoints For example setting $whitelistObjectTypes = array('document', 'event')`; enable '/documents' and '/events' endpoints that filter objects respectively by document and event object type.	# `array()`
`protected array`	`$responseData` The response data for client The response data for client	# `array()`
`protected boolean`	`$autoResponse` If response has to be built automatically at the end of the action If response has to be built automatically at the end of the action See self::response() set autoResponse to false self::route() if autoResponse is true call self::response()	# `true`
`protected array`	`$paginationOptions` Pagination options used to paginate objects Default values are Pagination options used to paginate objects Default values are 'page' => 1, // the page to load 'pageSize' => 20, // the dimension of the page 'maxPageSize' => 100 // the max page dimension in a request If 'page' or 'page_size' are in query url then they override those default	# `array( 'page' => 1, 'pageSize' => 20, 'maxPageSize' => 100 )`
`private array`	`$postData` The POST data in request The POST data in request	# `array()`
`protected array`	`$objectsFilter` An array of filter to apply to objects An array of filter to apply to objects	# `array()`
`protected string`	`$requestMethod` The request method invoked (get, post, put, delete) The request method invoked (get, post, put, delete)	# `null`
`private string`	`$fullApiBaseUrl` The complete base url for API i.e. https://example.com/api/v1 It is filled the first time self::baseUrl() is called The complete base url for API i.e. https://example.com/api/v1 It is filled the first time self::baseUrl() is called	# `null`
`protected array`	`$allowedObjectsUrlPath` The allowed url path you can apply to /objects endpoint. The url path is divided by request type 'get', 'post', 'put' and 'delete' The allowed url path you can apply to /objects endpoint. The url path is divided by request type 'get', 'post', 'put' and 'delete' For example GET /objects/1/children search the children of object with id = 1 Override in ApiController to limit or add functionality to /objects endpoint For example adding to 'get' array 'foo' filter and adding ApiController::getObjectsFoo() you can call /objects/1/foo All filters must have a corresponding class method built as self::requestMethod + Objects + filter camelized, for example: - getObjectsChildren() maps $allowedObjectsUrlPath['get']['children'] - postObjectsRelations() maps $allowedObjectsUrlPath['post']['relations']	# `array( 'get' => array( 'relations', 'children', 'contents', 'sections', 'descendants', 'siblings', //'ancestors', //'parents' ), 'post' => array( 'relations', 'children' ), 'put' => array( 'relations', 'children' ), 'delete' => array( 'relations', 'children' ) )`
`private array`	`$defaultAllowedUrlParams` The default supported url query string parameters names for every endpoint It's an array as The default supported url query string parameters names for every endpoint It's an array as array( 'endpoint_1' => array('name_one'), 'endpoint_2' => array('name_one', 'name_two'), ... ) keys starting with '_' are special words that defines groups of string names to reuse in endpoints i.e. array( '_groupOne' => array('name1', 'name2') 'endpoint_1' => array('name_one', '_groupOne'), // it's like array('name_one', 'name1', 'name2') 'endpoint_2' => array('_groupOne') // it's like array('name1', 'name2') ) Key '__all' it's a special key that contains query string names valid for every endpoint and every request method. Other endpoints params are only valid for GET requests.	# `array( '__all' => array('access_token'), '_pagination' => array('page', 'page_size'), 'objects' => array('id', 'filter[object_type]', 'filter[substring]', 'filter[query]', 'embed[relations]', '_pagination'), 'posters' => array('id', 'width', 'height', 'mode') )`
`protected array`	`$allowedUrlParams` Other supported query string parameters names for every endpoint. Override it according to your needs. Other supported query string parameters names for every endpoint. Override it according to your needs. See self::$defaultAllowedUrlParams to the right format	# `array()`

Properties inherited from FrontendController

$annotationOptions, $baseLevel, $captchaOptions, $checkPubDate, $logged, $loginRedirect, $logoutRedirect, $objectCache, $publication, $searchOptions, $sectionOptions, $showUnauthorized, $tagOptions, $xmlFormat

Properties inherited from AppController

$BeObjectCache, $currLang, $currLocale, $current, $ext, $fullBaseUrl, $helpers, $historyItem, $modelBindings, $moduleList, $moduleName, $modulePerms, $objectData, $profiling, $result, $skipCheck, $view

Classes

Interfaces

Exceptions

Class ApiBaseController

Methods summary

Overrides

Parameters

Returns

Returns

Returns

Overrides

Returns

Overrides

Returns

Throws

Overrides

Parameters

Parameters

Throws

Overrides

Parameters

Returns

Parameters

Parameters

Returns

Parameters

See

Parameters

Parameters

Parameters

Overrides

Parameters

Overrides

Parameters

See

Parameters

See

Parameters

Parameters

Parameters

Parameters

Parameters

Returns

Parameters

See

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Parameters

Parameters

Returns

Methods inherited from FrontendController

Methods inherited from AppController

Constants summary

Constants inherited from FrontendController

Constants inherited from AppController

Properties summary

See

See

See

Properties inherited from FrontendController

Properties inherited from AppController