Added API listing filtering & cleaned ApiAuthenticate returns

API listing endpoint filter can be found via &filter[name]=my+book query
parameters. There are a range of operators that can be used such as
&filter[id:gte]=4

app/Http/Controllers/Api/ApiController.php

@@ -14,7 +14,7 @@ class ApiController extends Controller
      */
     protected function apiListingResponse(Builder $query, array $fields): JsonResponse
     {
-        $listing = new ListingResponseBuilder($query, $fields);
+        $listing = new ListingResponseBuilder($query, request(), $fields);
         return $listing->toResponse();
     }
 }

app/Http/Controllers/Api/BooksApiController.php

@@ -4,6 +4,15 @@ use BookStack\Entities\Book;
 
 class BooksApiController extends ApiController
 {
+    public $validation = [
+        'create' => [
+            // TODO
+        ],
+        'update' => [
+            // TODO
+        ],
+    ];
+
     /**
      * Get a listing of books visible to the user.
      */
@@ -15,4 +24,24 @@ class BooksApiController extends ApiController
             'restricted', 'image_id',
         ]);
     }
+
+    public function create()
+    {
+        // TODO -
+    }
+
+    public function read()
+    {
+        // TODO -
+    }
+
+    public function update()
+    {
+        // TODO -
+    }
+
+    public function delete()
+    {
+        // TODO -
+    }
 }

app/Http/Middleware/ApiAuthenticate.php

@@ -2,7 +2,7 @@
 
 namespace BookStack\Http\Middleware;
 
-use BookStack\Exceptions\ApiAuthException;
+use BookStack\Exceptions\UnauthorizedException;
 use Closure;
 use Illuminate\Http\Request;
 
@@ -14,31 +14,37 @@ class ApiAuthenticate
      * Handle an incoming request.
      */
     public function handle(Request $request, Closure $next)
+    {
+        // Validate the token and it's users API access
+        try {
+            $this->ensureAuthorizedBySessionOrToken();
+        } catch (UnauthorizedException $exception) {
+            return $this->unauthorisedResponse($exception->getMessage(), $exception->getCode());
+        }
+
+        return $next($request);
+    }
+
+    /**
+     * Ensure the current user can access authenticated API routes, either via existing session
+     * authentication or via API Token authentication.
+     * @throws UnauthorizedException
+     */
+    protected function ensureAuthorizedBySessionOrToken(): void
     {
         // Return if the user is already found to be signed in via session-based auth.
         // This is to make it easy to browser the API via browser after just logging into the system.
         if (signedInUser()) {
-            if ($this->awaitingEmailConfirmation()) {
-                return $this->emailConfirmationErrorResponse($request);
-            }
-            return $next($request);
+            $this->ensureEmailConfirmedIfRequested();
+            return;
         }
 
         // Set our api guard to be the default for this request lifecycle.
         auth()->shouldUse('api');
 
         // Validate the token and it's users API access
-        try {
-            auth()->authenticate();
-        } catch (ApiAuthException $exception) {
-            return $this->unauthorisedResponse($exception->getMessage(), $exception->getCode());
-        }
-
-        if ($this->awaitingEmailConfirmation()) {
-            return $this->emailConfirmationErrorResponse($request, true);
-        }
-
-        return $next($request);
+        auth()->authenticate();
+        $this->ensureEmailConfirmedIfRequested();
     }
 
     /**
@@ -51,6 +57,6 @@ class ApiAuthenticate
                 'code' => $code,
                 'message' => $message,
             ]
-        ], 401);
+        ], $code);
     }
 }

app/Http/Middleware/Authenticate.php

@@ -28,4 +28,22 @@ class Authenticate
 
         return $next($request);
     }
+
+    /**
+     * Provide an error response for when the current user's email is not confirmed
+     * in a system which requires it.
+     */
+    protected function emailConfirmationErrorResponse(Request $request)
+    {
+        if ($request->wantsJson()) {
+            return response()->json([
+                'error' => [
+                    'code' => 401,
+                    'message' => trans('errors.email_confirmation_awaiting')
+                ]
+            ], 401);
+        }
+
+        return redirect('/register/confirm/awaiting');
+    }
 }

app/Http/Middleware/ChecksForEmailConfirmation.php

@@ -2,10 +2,22 @@
 
 namespace BookStack\Http\Middleware;
 
+use BookStack\Exceptions\UnauthorizedException;
 use Illuminate\Http\Request;
 
 trait ChecksForEmailConfirmation
 {
+    /**
+     * Check if the current user has a confirmed email if the instance deems it as required.
+     * Throws if confirmation is required by the user.
+     * @throws UnauthorizedException
+     */
+    protected function ensureEmailConfirmedIfRequested()
+    {
+        if ($this->awaitingEmailConfirmation()) {
+            throw new UnauthorizedException(trans('errors.email_confirmation_awaiting'));
+        }
+    }
 
     /**
      * Check if email confirmation is required and the current user is awaiting confirmation.
@@ -21,22 +33,4 @@ trait ChecksForEmailConfirmation
 
         return false;
     }
-
-    /**
-     * Provide an error response for when the current user's email is not confirmed
-     * in a system which requires it.
-     */
-    protected function emailConfirmationErrorResponse(Request $request, bool $forceJson = false)
-    {
-        if ($request->wantsJson() || $forceJson) {
-            return response()->json([
-                'error' => [
-                    'code' => 401,
-                    'message' => trans('errors.email_confirmation_awaiting')
-                ]
-            ], 401);
-        }
-
-        return redirect('/register/confirm/awaiting');
-    }
 }