API Response

Package for standardizing the responses from the API of your Symfony based applications.

Content

• Installation
• Using
  • as NULL with code
  • as integer with default code
  • as string with default code
  • as string with code
  • as integer with code
  • as array
  • with additional content
• Use without data key
  • as NULL with code
  • as integer with default code
  • as string with default code
  • as string with code
  • as integer with code
  • as array
  • with additional content
• Best practice use with the Laravel Framework
• Copyright and License

Installation

To get the latest version of API Response, simply require the project using Composer:

$ composer require andrey-helldar/api-response

This command will automatically install the latest version of the package for your environment.

Or you can manually set the required version, following the table:

Package version	PHP version	Symfony version	Command
^4.0	5.6.9+	^3.0, ^4.0	composer require andrey-helldar/api-response:^4.0
^4.4.1	5.6.9+	^3.0, ^4.0, ^5.0	composer require andrey-helldar/api-response:^4.4
^5.0	7.1.3+	^4.0, ^5.0	composer require andrey-helldar/api-response:^5.0
latest	7.1.3+	^4.0, ^5.0	composer require andrey-helldar/api-response

Instead, you may of course manually update your require block and run composer update if you so choose:

{
    "require": {
        "andrey-helldar/api-response": "^5.0"
    }
}

Alright! Use api_response() helper.

[ to top ]

Using

as NULL with code:

return api_response(null, 304);

return with code 304:

{
    "data": null
}

[ to top ]

as integer with default code:

return api_response(304);

return with code 200:

{
    "data": 304
}

[ to top ]

as string with default code:

return api_response('qwerty');

return with code 200:

{
    "data": "qwerty"
}

[ to top ]

as string with code:

return api_response('qwerty', 400);

return with code 400:

{
  "error": {
    "code": 400,
    "data": "qwerty"
  }
}

[ to top ]

as integer with code:

return api_response(304, 400);

return with code 400:

{
  "error": {
    "code": 400,
    "data": 304
  }
}

[ to top ]

as array:

$data = [
    [
        'title' => 'Title #1',
        'description' => 'Description #1',
    ],
    [
        'title' => 'Title #2',
        'description' => 'Description #2',
    ],
];

[ to top ]

as error

return api_response($data, 400);

return with code 400:

{
  "error": {
    "code": 400,
    "data": [
      {
        "title": "Title #1",
        "description": "Description #1"
      },
      {
        "title": "Title #2",
        "description": "Description #2"
      }
    ]
  }
}

[ to top ]

as success

return api_response($data, 200);

return with code 200:

{
    "data": [
        {
            "title": "Title #1",
            "description": "Description #1"
        },
        {
            "title": "Title #2",
            "description": "Description #2"
        }
    ]
}

If the first parameter is a number, then the decryption of the error by code will be return. In other cases, the value of the passed variable will be return.

[ to top ]

with additional content

return api_response('title', 200, [], ['foo' => 'bar']);

return with code 200:

{
  "data": "title",
  "foo": "bar"
}

return with code 400:

{
  "error": {
    "code": 400,
    "data":"ok"
  },
  "foo": "bar"
}

return api_response(['data' => 'foo', 'bar' => 'baz']);

return with code 200:

{
  "data": "foo",
  "bar": "baz"
}

return with code 400:

{
  "error": {
    "code": 400,
    "data":"foo"
  },
  "bar": "baz"
}

[ to top ]

Use without data key

If you do not want to wrap the response in the data key, then you need to pass the false value to the 5th parameter of the function:

use Helldar\ApiResponse\Services\Response;
use Symfony\Component\HttpFoundation\JsonResponse;

/**
 * Return a new response from the application.
 *
 * @param mixed|null $data
 * @param int $status_code
 * @param array $headers
 * @param array $with
 * @param bool $use_data
 *
 * @return JsonResponse
 */
function api_response(
    $data = null,
    int $status_code = 200,
    array $headers = [],
    array $with = [],
    bool $use_data = true
)
{
    return Response::init()
        ->headers($headers)
        ->data($data, $use_data)
        ->with($with)
        ->status($status_code)
        ->response();
}

as NULL with code and without data key:

return api_response(null, 304, [], [], false);

return with code 304:

{}

[ to top ]

as integer with default code and without data key:

return api_response(304, 200, [], [], false);

return with code 200:

304

[ to top ]

as string with default code and without data key:

return api_response('qwerty', 200, [], [], false);

return with code 200:

"qwerty"

[ to top ]

as string with code and without data key:

return api_response('qwerty', 400, [], [], false);

return with code 400:

{
  "error": {
    "code": 400,
    "data": "qwerty"
  }
}

[ to top ]

as integer with code and without data key:

return api_response(304, 400, [], [], false);

return with code 400:

{
  "error": {
    "code": 400,
    "data": 304
  }
}

[ to top ]

as array and without data key:

$data = [
    [
        'title' => 'Title #1',
        'description' => 'Description #1',
    ],
    [
        'title' => 'Title #2',
        'description' => 'Description #2',
    ],
];

as error and without data key

return api_response($data, 400, [], [], false);

return with code 400:

{
  "error": {
    "code": 400,
    "data": [
      {
        "title": "Title #1",
        "description": "Description #1"
      },
      {
        "title": "Title #2",
        "description": "Description #2"
      }
    ]
  }
}

[ to top ]

as success and without data key

return api_response($data, 200, [], [], false);

return with code 200:

[
    {
        "title": "Title #1",
        "description": "Description #1"
    },
    {
        "title": "Title #2",
        "description": "Description #2"
    }
]

If the first parameter is a number, then the decryption of the error by code will be return. In other cases, the value of the passed variable will be return.

[ to top ]

with additional content and without data key:

return api_response('title', 200, [], ['foo' => 'bar'], false);

return with code 200:

{
  "data": "title",
  "foo": "bar"
}

return with code 400:

{
  "error": {
    "code": 400,
    "data":"ok"
  },
  "foo": "bar"
}

return api_response(['data' => 'foo', 'bar' => 'baz'], 200, [], [], false);

return with code 200:

{
  "data": "foo",
  "bar": "baz"
}

return with code 400:

{
  "error": {
    "code": 400,
    "data":"foo"
  },
  "bar": "baz"
}

[ to top ]

Best practice use with the Laravel Framework

To use you need to add three methods to the file app/Exceptions/Handler.php:

use Illuminate\Auth\Access\AuthorizationException;
use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use Illuminate\Validation\ValidationException;

class Handler extends ExceptionHandler
{
    public function render($request, Exception $exception)
    {
        $rendered = parent::render($request, $exception);

        return $this->isJson($request)
            ? api_response($rendered->getContent(), $rendered->getStatusCode())
            : $rendered;
    }

    protected function unauthenticated($request, AuthenticationException $exception)
    {
        return $this->isJson($request)
            ? api_response(__('errors.401', 401))
            : redirect()->guest(route('login'));
    }
    
    protected function invalidJson($request, ValidationException $exception)
    {
        return api_response($exception->errors(), $exception->status ?: 400);
    }
    
    protected function isJson($request): bool
    {
        return $request->expectsJson() || $request->isJson() || $request->is('api/');
    }
}

[ to top ]

Copyright and License

API Response was written by Andrey Helldar, and is licensed under the MIT License.

[ to top ]