Rest API Response Library
, (*1)
This Library provides a Response abstraction for RESTful JSON-API's on top of the Symfony HTTP-Foundation-Component., (*2)
The Library defines custom Exceptions and Exception-Interfaces for Error Handling., (*3)
There is a Response-Class for handling of successfull responses and an Error-Response-Class for Exception-Responses., (*4)
Install with Composer
composer require pmarien/rest-api-response
Version
If you use the symfony/http-foundation in any version lower than 3.0 please use version 1.* of these library., (*5)
If you use the symfony/http-foundation in any version higher than 3.0 please use version 2.* of these library., (*6)
Usage
JSON Output
Status:, (*7)
indicates, weather the request was successful or not, (*8)
Count:, (*9)
Number of results which are delivered within the results array, (*10)
Results:, (*11)
Array of one or more data objects (your data), (*12)
Success
{
"status": "success",
"count": 1,
"results": [
{
"custom": "data"
}
]
}
Error
{
"status": "error",
"count": 1,
"results": [
{
"code": 0,
"message": "Error Message",
"previous": null,
"data": [
"optional custom debug data, can be an object or an array"
]
}
]
}
Get a Response Object
$response = new ApiResponse(['message'=>'Hello World']);, (*13)
$errorResponse = new ApiResponse(new \Exception('Request failed!'));, (*14)
Object Handling
By default, protected and private properties of objects will be ignored be json_encode()., (*15)
To build a response from custom objects, this library provides an Interface (JsonEncodableInterface). Objects which implement these Interface can be handled on custom way., (*16)
Example
your Class, (*17)
class CustomObject implements JsonEncodableInterface {
/**
* @var string
*/
protected $publicForResponse = 'hello';
/**
* @var string
*/
protected $notPublic = 'world';
/**
* Return an array of properties which can be encoded as json
* @return array
*/
public function encode(){
return [
'public' => $this->publicForResponse
];
}
}
your Controller Action, (*18)
public function testAction(){
return new ApiResponse(new CustomObject());
}
Json-Response, (*19)
{
"status": "success",
"count": 1,
"results": [
{
"public": "hello"
}
]
}
Exceptions
There are four special Exceptions and Interfaces defined in this Library:, (*20)
ExceptionInterface:, (*21)
Provides a Method called "getMetaData" which should return an array with custom debug data for the error response, (*22)
UncriticalExceptionInterface:, (*23)
If an Exception implements these Interface, the error response will return the error object and status but with a HTTP-Status-Code 200 (Ok), (*24)
CriticalExceptionInterface:, (*25)
With these Interface you are able to define a custom HTTP-Status-Code instead of the default 500 (Internal Server Error) Status, (*26)
ExceptionListInterface:, (*27)
With these Interface you are able to define more than one error result object for one response, (*28)
Please note that your custom Exception must extend the basic php exception, even if you implement one ore more of the interfaces., (*29)
There are also predefined exceptions ready to use:, (*30)
UncriticalException:, (*31)
Implements the ExceptionInterface and the UncriticalExceptionInterface, (*32)
CriticalException:, (*33)
Implements the ExceptionInterface and the CriticalExceptionInterface, (*34)
UncriticalExceptionExceptionList:, (*35)
Implements the ExceptionInterface, the UncriticalExceptionInterface and the ExceptionListInterface, (*36)
CriticalExceptionExceptionList:, (*37)
Implements the ExceptionInterface, the CriticalExceptionInterface and the ExceptionListInterface, (*38)
Licence
This library is under MIT Licence., (*39)
Wallogit.com
