Laravel API Response
This package aims to help you standardize all your API responses in a simple and structured way.
By default, the stucture of the API response looks like this:
{
"success": true,
"title": "Users",
"message": "Active users only",
"data": [
// users...
],
"errors": [],
}
Note: For now, if you want to customize the response structure, you need to manually extend
ApiResponseclass and overridetoResponsemethod.
Install
$ composer require kodepandai/laravel-api-response
Usage
The ApiResponse class implement a Fluent trait from laravel, so you can chain methods as you like. See the example below.
Return a success response
use Illuminate\Http\Response;
use KodePandai\ApiResponse\ApiResponse;
ApiResponse::success(['version' => 'v1.0.0']);
ApiResponse::success(['name' => 'Taylor Otwell'])
->title('User')
->message('User Data');
ApiResponse::success()
->statusCode(Response::HTTP_CREATED)
->message('Sucessfully create a user.');
Return an error response
By default the statusCode for error API response is HTTP_BAD_REQUEST.
use Illuminate\Http\Response;
use KodePandai\ApiResponse\ApiResponse;
ApiResponse::error()
->title('Failed')
->message('Only admin can delete a user.');
ApiResponse::error(['email' => ['The email field is required.']])
->statusCode(Response::HTTP_UNPROCESSABLE_ENTITY);
ApiResponse::error()
->statusCode(Response::HTTP_SERVICE_UNAVAILABLE)
->message('Out of service, please comeback later.');
Validate or Fail
Use this helper to validate user submitted request, then return an ApiResponse::error response if the validation fails.
With this helper, now you can use something like $request->validate() without worrying on how to handle the redirect response or validation errors separately.
// without helper
// in the controller, using validate helper.
// if not handled correctly, it can return a redirect reponse instead of json response
$request->validate(['email' => 'required']);
// or using validator
$validator = Validator::make(['email' => 'required']);
if ($validator->fails()) {
return JsonResponse($validator->errors());
}
//----
// with this helper
// it will automatically return a json response if validation fails
// if the validation passes, it will return validated data
$validatedData = ApiResponse::validateOrFail([
'email' => 'required|email',
'username' => 'required|unique:users,username',
]);
Throwing an Exception
Instead of using ApiResponse manually, you can also throw an exception and will get the same response according to the exception type.
This package provides two exception: ApiException and ApiValidationException.
ApiException: throw an api errorApiValidationException: throw a validation error
if (! DB::hasDriver('mysql')) {
throw new ApiException('Mysql driver not found!', Response::HTTP_INTERNAL_SERVER_ERROR);
}
if ($user->balance <= 100_000) {
throw new ApiValidationException(['balance' => ['Balance must be greater than 100K']]);
}
Handling all Exception
If you would like to convert all laravel exception to return an ApiResponse, you can use the ExceptionHandler::renderAsApiResponse helper.
// file: Exception/Handler.php
use KodePandai\ApiResponse\ExceptionHandler;
// new laravel (>= 8)
public function register()
{
$this->renderable(function (Throwable $e, $request) {
if ($request->wantsJson()) {
return ExceptionHandler::renderAsApiResponse($e);
}
});
}
// old laravel (<= 7)
public function render($request, Throwable $exception)
{
if ($request->wantsJson()) {
return ExceptionHandler::renderAsApiResponse($exception);
}
return parent::render($request, $exception);
}
Develop
- To test run
composer test.
4 Dec 17, 2022
342 Dec 31, 2022
441 Jan 5, 2023
776 Dec 25, 2022
2 Feb 9, 2022
43 Nov 20, 2022
1.9k Dec 29, 2022
624 Dec 30, 2022
61 Dec 30, 2022
0 Jun 29, 2022
4 Nov 29, 2022
129 Dec 31, 2022
614 Dec 26, 2022
1k Dec 16, 2022
1 Aug 7, 2022
25 Oct 12, 2022
158 Dec 25, 2022
340 Jan 6, 2023
61 Nov 5, 2022