maxhill/api

Laravel Api package

Laravel api setup

All the api setup I dread creating for every project. Concised down to a single plugin., _(*1)

• It gives you JSON-webtoken authentication (using the awesome tymondesigns/jwt-auth).
• It gives you model transformation (using the fantastic fractal-package)
• It also gives you some sweet api-helper methods for returning resources and errors and more.

Install

1. Add service provider.

// config/app.php
...
Maxhill\Api\ApiServiceProvider::class,
...

1. Add route middleware.

// app/Http/Kernel.php
...
'jwt.auth' => 'Tymon\JWTAuth\Middleware\GetUserFromToken',
'jwt.refresh' => 'Tymon\JWTAuth\Middleware\RefreshToken',
...

1. Publish vendors.

$ php artisan vendor:publish --provider="Maxhill\Api\ApiServiceProvider"
$ php artisan vendor:publish --provider="Tymon\JWTAuth\Providers\JWTAuthServiceProvider"

1. Generate jwt-secret.

$ php artisan jwt:generate

1. Remove csrf-token middleware.

// app/Http/Kernel.php
'Illuminate\Foundation\Http\Middleware\VerifyCsrfToken',

Usage

Authentication

• Use route middleware

Require the user to be logged in to access a route:, _(*2)

Route::post('whatever', [
    'uses' =>'WhateverController@index',
    'middleware' => 'jwt.auth'
]);

Read more * Use authenticate routes, _(*3)

Authentication is already setup. Just post to /authenticate with the email and password of the user you want to sign in., _(*4)

You may change the /authenticate-route to whatever you like in the config file config/api.php, _(*5)

Controllers

Extend ApiController.

Make sure your api-controllers extends Maxhill\Api\Http\Controllers\ApiController; and not the default App\Http\Controller, _(*6)

Use transformers for returning.

Example user model transformer;, _(*7)

<?php
# app/Transformers/UserTransformer.php

namespace App\Transformers;

use App\User;
use League\Fractal\TransformerAbstract;

class UserTransformer extends TransformerAbstract
{

    /**
     * Turn this item object into a generic array
     *
     * @param User $user
     * @return array
     */
    public function transform(User $user)
    {
        return [
            'id' => (int)$user->id,
            'name' => $user->name,
            'email' => $user->email
        ];
    }

}

Using the UserTransformer:, _(*8)

    # app/Http/Controllers/WhateverController.php

    public function index()
    {
        $users = User::all();
        return $this->respondWithCollection($users, new UserTransformer);
    }

ApiController - methods

• user() // Returns false or user object parsed from auth token

Respond with data:

• respondWithItem()
• respondWithCollection()
• respondWithArray()

Error-responses:

• respondWithError()
• errorForbidden()
• errorInternalError()
• errorNotFound()
• errorUnauthorized()
• `errorWrongArgs()