hpolthof/laravel-api

An API rendering package for Laravel 5

Uniform API rendering for Laravel 5

, _(*1)

This package was created for an internal project, but as the idea is reusable, I encourage others to make use of this package., _(*2)

The main goal was to create an uniform way of presenting API output, and the creation of a layer between data structure and output., _(*3)

Installation

Require this package with composer:, _(*4)

composer require hpolthof/laravel-api

Add the follow service provider to your config/app.php:, _(*5)

'Hpolthof\LaravelAPI\APIServiceProvider',

Middleware

A new middleware named api.errors will be added to your list of available middleware., _(*6)

If you're using Laravel 5.3, this middleware will also be added into the api middleware group., _(*7)

Usage

To use this package you should implement the Hpolthof\LaravelAPI\Contracts\ShouldMorphAPI interface onto an Eloquent model., _(*8)

You'll have to implement the function bindAPI() and have to return an instance of Hpolthof\LaravelAPI\Binding., _(*9)

Like this:, _(*10)

public function bindAPI()
{
    return Binding::create([
        'street' => $this->street,
        'street_nr' => $this->number,
        'street_suffix' => $this->suffix,
        'postcode' => $this->zip,
        'city' => $this->city,
    ]);
}

In a controller you can then return the following:, _(*11)

public function index()
{
    $items = Address::all();
    return \Response::api($items);
}

public function show($id)
{
    $item = Address::find($id);
    return \Response::api($item);
}

The response would look something like this:, _(*12)

{
    "header": {
        "request": {
            "location": "http:\/\/localhost:8000\/api\/addresses",
            "method": "GET",
            "parameters": []
        },
        "response": {
            "status": 200,
            "error": null,
            "timestamp": "2016-11-28 14:09:35"
        }
    },
    "content": [
        {
            "street": "Van der Polweg",
            "street_nr": 17,
            "street_suffix": "",
            "postcode": "3384HD",
            "city": "Amersfoort",
        },
        {
            "street": "Van der Polweg",
            "street_nr": 15,
            "street_suffix": "",
            "postcode": "3384HD",
            "city": "Amersfoort",
        }
    ]
}

Error messages

Sometimes you'll need to force an error to the user, this can be done by throwing an exception. The package also provides some specific exceptions that should be used where relevant., _(*13)

Hpolthof\LaravelAPI\Exceptions\AccessDeniedException Hpolthof\LaravelAPI\Exceptions\BadRequestException Hpolthof\LaravelAPI\Exceptions\NotFoundException Hpolthof\LaravelAPI\Exceptions\NotImplementedException, _(*14)

This would result in something like:, _(*15)

json { "header": { "request": { "location": "http:\/\/localhost:8000\/api\/addresses", "method": "GET", "parameters": [] }, "response": { "status": 403, "error": "Forbidden", "timestamp": "2016-11-28 15:05:29" } } }, _(*16)