Class HttpApiV2Controller
Class HttpApiV2Controller
Contains common functionality for all the GX2 APIv2 controllers. You can use the $api instance in the
child-controllers in order to gain access to request and response information. The $uri variable is an
array that contains the requested resource path.
You can use a protected "__initialize" method in your child controllers for performing common operations
without overriding the parent constructor method.
This class contains some private methods that define the core operations of each controller and should
not be called from a child-controller (like validation, authorization, rate limiting). The only way to
disable the execution of these methods is to override the controller.
-
AbstractApiV2Controller
-
HttpApiV2Controller
Direct known subclasses
AbstractImagesApiV2Controller,
AddressesApiV2Controller,
OrdersItemsApiV2Controller,
OrdersItemsAttributesApiV2Controller,
OrdersTotalsApiV2Controller,
ProductsApiV2Controller,
ProductsLinksApiV2Controller,
ZonesApiV2Controller,
AttachmentsApiV2Controller,
CategoriesApiV2Controller,
CountriesApiV2Controller,
CustomersApiV2Controller,
DefaultApiV2Controller,
EmailsApiV2Controller,
OrdersApiV2Controller,
OrdersHistoryApiV2Controller
Methods summary
protected
|
#
_sortResponse( array & $response )
Sort response array with the "sort" GET parameter.
Sort response array with the "sort" GET parameter.
This method supports nested sort values, so by providing a "+address.street" value
to the "sort" GET parameter the records will be sort by street value in ascending
order. Method supports sorting up to 5 fields.
Important #1: This method has some advantages and disadvantages over the classic database sort mechanism. First it does not need mapping between the API fields and the database fields. Second it does not depend on external system code to sort the response items, so if for example a domain-service does not support sorting the result can still be sorted before sent to the client. The disadvantages are that it will only support a predefined number of fields and this is a trade-off because the method should not use the "eval" function, which will introduce security risks. Furthermore it might be a bit slower than the database sorting.
Important #2: This method is using PHP's array_multisort which by default will sort strings in a case sensitive manner. That means that strings starting with a capital letter will come before strings starting with a lowercase letter. http://php.net/manual/en/function.array-multisort.php
Example: // will sort ascending by customer ID and descending by customer company api.php/v2/customers?sort=+id,-address.company
Parameters
- $response
Passed by reference, contains an array of the multiple items
that will returned as a response to the client.
|
protected
|
#
_minimizeResponse( array & $response )
Minimize response using the $fields parameter.
Minimize response using the $fields parameter.
APIv2 supports the GET "fields" parameter which enables the client to select the
exact fields to be included in the response. It does not support nested fields,
only first-level.
You can provide both associative (single response item) or sequential (multiple response
items) arrays and this method will adjust the links accordingly.
Parameters
- $response
- Passed by reference, it will be minified to the required fields.
|
protected
|
#
_paginateResponse( array & $response )
Paginate response using the $page and $per_page GET parameters.
Paginate response using the $page and $per_page GET parameters.
One of the common functionalities of the APIv2 is the pagination and this can be
easily achieved by this function which will update the response with the records
that need to be returned. This method will automatically set the pagination headers
in the response so that client apps can easily navigate through results.
Parameters
- $response
- Passed by reference, it will be paginated according to the provided parameters.
|
protected
|
#
_linkResponse( array & $response )
Include links to response resources.
Include links to response resources.
The APIv2 operates with simple resources that might be linked with other resources. This
architecture promotes flexibility so that API consumers can have a simpler structure. This
method will search for existing external resources and will add a link to the end of each
resource.
IMPORTANT: If for some reason you need to include custom links to your resources
do not use this method. Include them inside your controller method manually.
NOTICE #1: This method will only search at the first level of the resource. That means that
nested ID values will not be taken into concern.
NOTICE #2: You can provide both associative (single response item) or sequential (multiple response
items) arrays and this method will adjust the links accordingly.
Parameters
- $response
Passed by reference, new links will be appended into the end
of each resource.
|
protected
|
#
_writeResponse( array $response, integer $p_statusCode = 200 )
Write JSON encoded response data.
Write JSON encoded response data.
Use this method to write a JSON encoded, pretty printed and unescaped response to
the client consumer. It is very important that the API provides pretty printed responses
because it is easier for users to debug and develop.
IMPORTANT: PHP v5.3 does not support the JSON_PRETTY_PRINT and JSON_UNESCAPED_SLASHES so
this method will check for their existance and then use them if possible.
Parameters
- $response
- Contains the response data to be written.
- $p_statusCode
- (optional) Provide a custom status code for the response, default 200 - Success.
|
protected
boolean
|
#
_mapResponse( array $criteria )
Map the sub-resource to another controller.
Map the sub-resource to another controller.
Some API resources contain many subresources which makes the creation of a single
controller class complicated and hard to maintain. This method will forward the
request to a another controller by checking the provided criteria.
Example:
$criteria = array( 'items' => 'OrdersItemsAttributesApiV2Controller', 'totals' => 'OrdersTotalsApiV2Controller'
);
Notice: Each controller should map a direct subresource and not deeper ones. This way
every API controller is responsible to map its direct subresources.
Parameters
- $criteria
- An array containing the mapping criteria.
Returns
boolean
Returns whether the request was eventually mapped.
Throws
|
protected
|
#
_searchResponse( array & $response, string $p_keyword )
Perform a search on the response array.
Perform a search on the response array.
Normally the best way to filter the results is through the corresponding service but some times
there is not specific method for searching the requested resource or subresource. When this is
the case use this method to filter the results of the response before returning them back to the
client.
Parameters
- $response
- Contains the response data to be written.
- $p_keyword
- The keyword to be used for the search.
Throws
InvalidArgumentException
If search keyword parameter is not a string.
|
protected
|
#
_locateResource( string $p_name, integer $p_id )
Add location header to a specific response.
Add location header to a specific response.
Use this method whenever you want the "Location" header to point to an existing resource so that
clients can use it to fetch that resource without having to generate the URL themselves.
Parameters
Throws
InvalidArgumentException
If the arguments contain an invalid value.
|
protected
string
|
#
_setJsonValue( string $jsonString, string $property, string $value )
Parameters
- $jsonString
- The json formatted string which should be updated.
- $property
- The name or key of the property which should be updated.
- $value
- The new value which should be set.
Returns
string
The updated json formatted string.
|