Need help architecting or implementing a REST API? Book a call!

Guide

Security

Learn about authentication, authorization, and validation.

Authentication

Orion does not provide any authentication perks at the moment, assuming that developer is responsible for setting up the desired app's authentication capabilities. Hovewer, we recommend using Laravel Passport or Laravel Sanctum for this purpose.

Authorization

Both model and relation controllers rely on model policies to determine whether currently authenticated user is allowed to perform certain actions or not.

While it is not recommended, but in some situations you may want to disable authorization checks on a particular controller. To do so, you can use Orion\Concerns\DisableAuthorization trait.

<?php

namespace App\Http\Controllers\Api;

use App\Models\Post;
use Orion\Concerns\DisableAuthorization;

class PostsController extends ApiController
{
    use DisableAuthorization;

    /**
     * @var string $model
     */
    protected $model = Post::class;
}

Usage with Sanctum (or any other custom Auth guard)

By default, api guard is used to resolve the currently authenticated user for authorization.

However, you can change the way the user is resolved by overriding resolveUser method on a controller.

<?php

namespace App\Http\Controllers\Api;

use App\Models\Post;

class PostsController extends ApiController
{
    /**
     * @var string $model
     */
    protected $model = Post::class;

     /**
     * Retrieves currently authenticated user based on the guard.
     *
     * @return \Illuminate\Contracts\Auth\Authenticatable|null
     */
    public function resolveUser()
    {
        return Auth::guard('sanctum')->user();
    }
}

Validation

Request classes must extend Orion\Http\Requests\Request class instead of Illuminate\Foundation\Http\FormRequest.

To validate incoming requests data to store and update endpoints, Orion will try to find request class for resource model following the class name pattern: App\Http\Requests\<model>Request.

For example, if you have App\Models\Message model, the related request class would be App\Http\Requests\MessageRequest.

If request class names in your app do not follow this naming convention or if you just would like to be more explicit, set protected $request property on controller to a fully-qualified request class name.

<?php

namespace App\Http\Controllers\Api;

use App\Models\Message;
use App\Http\Requests\CustomMessageRequest;

class MessagesController extends ApiController
{
    /**
     * @var string $model
     */
    protected $model = Message::class;

    /**
    * @var string $request
    */
    protected $request = CustomMessageRequest::class;
}

The request class is then binded using Laravel Service Container and used in store and update methods to validate request data the same way as if you would explicitly set it in method signature:

public function store(CustomMessageRequest $request)
{
    ...
}

Validation Rules

Defining rules for store and update endpoints

Orion provides Orion\Http\Requests\Request class with a handful of methods to specify validation rules.

To define common rules for both store and update endpoints you can use commonRules method. If you would like to define rules specific to endpoint you can use storeRules and updateRules methods.

Rules specified in storeRules and updateRules methods are merged with rules from commonRules method.
<?php

namespace App\Http\Requests;

use Orion\Http\Requests\Request;

class PostRequest extends Request
{
    public function commonRules() : array
    {
        return [
            'title' => 'required'
        ];
    }

    public function storeRules() : array
    {
        return [
            'status' => 'required|in:draft,review'
        ];
    }
}

In this example, when request is made to store endpoint, both title and status fields will be required. However, when request method is made to update endpoint, only title field would be required, because there is no other rules defined in updateRules method and title field is marked as required in the commonRules method.

Defining rules for relation methods

You can also define rules for relation specific endpoints: associateRules, attachRules, detachRules, syncRules, toggleRules, updatePivotRules.

Rules specified in these methods are NOT merged with rules from commonRules method.

Defining rules for batch operations

You can also define rules for batch endpoints: batchStore, batchUpdate.


Copyright © 2019-2024 Aleksei Zarubin