DEV Community

Cover image for Force JSON response on all API routes in Laravel
Pavel Kutáč
Pavel Kutáč

Posted on • Updated on

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';
});


Enter fullscreen mode Exit fullscreen mode

Examples of HTML responses on API routes

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);
    }
}


Enter fullscreen mode Exit fullscreen mode


namespace App\Http;

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


Enter fullscreen mode Exit fullscreen mode


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


Enter fullscreen mode Exit fullscreen mode

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');
});


Enter fullscreen mode Exit fullscreen mode

Top comments (7)

Collapse
 
jimnayzium profile image
Jim Nayzium

Can you confirm how to do this in Laravel 11 to accomplish the exact same thing. "To auto-add the "Accept: application/json" to the header request.

Collapse
 
yanbrasiliano profile image
Yan Brasiliano Silva Penalva

Hey bro, if you want to use this solution in Laravel 11, follow this step-by-step:

  1. Create the middleware similar to this post
  2. In app.php, import middleware and apply it like this:

->withMiddleware(function (Middleware $middleware) {
$middleware->prependToGroup('api', [
ForceJsonResponse::class,
]);
})

This middleware needs to come first to work.

Collapse
 
arxeiss profile image
Pavel Kutáč

Thanks for update. I will need to check.

I think this is needed only in new App structure. But even I upgrade my app regularly, old way is still supported, so I didn't notice any issues.

Collapse
 
ercogx profile image
Vitalik

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

Collapse
 
arxeiss profile image
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',
    ],
Enter fullscreen mode Exit fullscreen mode
Collapse
 
back2lobby profile image
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

Collapse
 
ercogx profile image
Vitalik

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