Force JSON response on all API routes in Laravel

Laravel often returns an HTML response or redirect response on API routes, mostly if the response is an error one. However, it is quite easy to force Laravel to return JSON response in those cases.

🇨🇿 V češtině si lze článek přečíst na kutac.cz

---

You can simulate the described behavior by adding the code below into the routes/api.php file and doing requests in Postman or browser. On the image, you can see some HTML responses in such cases.

use Carbon\Carbon;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::get('health-check', function () {
    return response()->json([ 'status' => 'OK', 'timestamp' => Carbon::now() ]);
});
Route::post('settings', function (Request $request) {
    $request->validate([ 'entry' => 'required|string|min:5' ]);
    return 'OK';
});

How to force JSON response

Laravel checks the Accept header in the request. Then deciding according to this header, which response it should send back. But browser or Postman often sends Accept: */*. So it is enough to rewrite this header and the rest will be handled by Laravel.

Custom middleware and route fallback

Middleware is the best friend to achieve this. First, create the file app/Http/Middleware/ForceJsonResponse.php or use php artisan make:middleware ForceJsonResponse. Second, register the created middleware in app/Http/Kernel.php. The last step, adding the fallback route to routes/api.php is optional but recommended.

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class ForceJsonResponse
{
    public function handle(Request $request, Closure $next)
    {
        $request->headers->set('Accept', 'application/json');
        return $next($request);
    }
}

namespace App\Http;

class Kernel extends \Illuminate\Foundation\Http\Kernel
{
    ...
    protected $middlewareGroups = [
        ...
        'api' => [
            \App\Http\Middleware\ForceJsonResponse::class,
            ...
        ],
    ];
}

// routes/api.php
Route::fallback(function (){
    abort(404, 'API resource not found');
});

There can be still HTML response

The code will solve JSON responses in error cases. But Laravel returns HTML if the controller is returning a string. For example 3 on the image above will be still text/html response. This can be handled by middleware as well. It is described on DarkGhostHunter blog. But I don't like this solution and I prefer returning JSON response directly. So, update the code like this:

Route::post('settings', function (Request $request) {
    $request->validate([ 'entry' => 'required|string|min:5' ]);
    // return 'OK';
    return response()->json('OK');
});

Comments

[Vitalik]

It doesn't seem to work with Route Model Binding. It returns a 404 error with HTML

[Pavel Kutáč]

Well, in example above I showed it should be first in api section. This is how I use it.

'api' => [
        \App\Http\Middleware\ForceJsonResponse::class,
        'throttle:60,1',
        'bindings',
    ],

[8ack2Lobby]

ForceJsonResponse should be before the throttle:api if you want that 429 response and model not found response (when use model binding in controller) to be also returned as json ~ credits @ercog7921 on yt comment

[Vitalik]

Oops looks like ForceJsonResponse middleware should be higher than \Illuminate\Routing\Middleware\SubstituteBindings::class