-
Notifications
You must be signed in to change notification settings - Fork 12
Fundamentals
And end point in the API represents a resource which client applications can perform actions on. Each end point can support any number of defined RESTish verbs like POST, GET etc. The minimum set of files an end point requires is a Controller, Model, Entity and Route. An end point is nearly always backed by a database table and the API only support SQL based persistence layers supported by Phalcon.
A model is a normal Phalcon object that you are probably already familiar with. The API contains an extended version of a Phalcon Model that you should base all models off of from within your application. A model represents a table from your persistence layer. Each Phalcon model expects a primary key which is often detected via Phalcon::ORM. The upstream Entity object depends on a model to perform crud operations. As such it is best to use the model for low level data validation and any business logic concerned with data contained within the table. Use Phalcon's built in ORM to describe hasOne, belongsTo and hasMany relationships which enable the larger end point to side load related records based on user requests.
A Model is a camel cased table name, which should be plural. IE. MyTablesNames
An entity is a custom construct of the API. It acts as a layer of abstraction that sits between a controller and a model. The job of an entity is to contain high level business logic that coordinates among models for CRUD operations. The Entity delegates most the respectability of parsing incoming read requests to the searchHelper.
An Entity is a camel cased singular version of the table name with as suffix of Entity. IE. MyTableNameEntity
A controller is also a normal Phalcon object with some specific enhancements for performing it's responsibilities. It catches requests from a calling client (ie a web browser) and gathers any specific data before delegating work to an underlying entity. The controller also formats data returned from an Entity into the correct format configured in the API. JSON responses are the most tested, but an abstraction layer provides an option to use a different response format.
A Controller is a camel cased singular version of the table name with the suffice of Controller. IE MyTableNameController
Used to define the verbs your API supports. Connects each verb to an action on the controller.
A Route is named exactly after the table name.
A SearchHelper works in conjunction with an entity to further guide the API in gathering and formating data. Specifically, a SearhcHelper drives entity behavior around building relationships, filtering data and showing or hiding columns.
There are a handful of configuration options that you as a developer can set to force API behavior for a particular end point. All of these values should be configured in the provided root function inside the Entity. configureSearchHelper.
/**
* the maximum number of primary records to be returned by the api in any given call
*
* @var int
*/
public $entityLimit = 500;
/**
* used for paginating results but kind of dumb to set from the server side, why not leave it only for the client to request?
*
* @var int
*/
public $entityOffset = null;
/**
* can be any of the following
*
* block
* prevent any relationships from being side-loaded regardless
* of what the client asked for
*
* comma, separated, list
* a list of supplied relationships
*
* all
* provide all available relationships
*
* none
* entity makes provides no relationships but can be overridden by client
*
* entity suggested relationships are only provided if nothing specific is requested by the client
*
* @var string
*/
public $entityWith = 'none';
// a default sort order that could be over ridden by a client submitted value
// ie. field1,-field2
public $entitySort = null;