Be part of JetBrains PHPverse 2026 on June 9 – a free online event bringing PHP devs worldwide together.

BunnehMike's avatar

API Resources/Collections vs response()->json()

I'm trying to wrap my head around using the API Resources/Collections. I must be missing something, as it feels as if response()->json(['data' => $data]) is just easier to use with less code/files involved.

Would someone please explain to me why I should use a Resource/Collection as opposed to just using the JSON response in the controller? I know there must be a reason for it or it wouldn't exist, I'm just having a hard time understanding it. I have read the documentation over and over again, and it's just not clicking as to why use it.

For example. Why use this?

public function index()
{
    return UserResource::collection(User::all());
}

public function show($id)
{
    return new UserResource(User::find($id));
}

Instead of just doing this?

public function index()
{
    return response()->json([
        'users' => User::all(),
    ]);
}

public function show($id)
{
    return response()->json([
        'user' => User::find($id),
    ]);
}
0 likes
6 replies
rodrigo.pedra's avatar

Sometimes you want a fine-grained control over the attributes you want to send in the response, or change some attributes names, or do some specific formatting on attributes (depending on frontend requirements).

So Resources offers the chance to you define the shape of your response without modifying a database table or messing with append/hidden attributes on Eloquent models.

One common case in my apps is that for some screens I want to send different set of fields/related models to the frontend, for example on a user Orders' history I might not include in the response fields related to administrative tasks. But on the admin area those fields are desirable/needed.

In that case I have two different Resource classes and return each when needed.

Hope it helps =)

2 likes
BunnehMike's avatar

It's starting to make a little more sense now.

A follow up question with this in mind. When to use an Accessor vs changing the data in the Resource for the response?

My first guess would be, sometimes we want that Accessor to be formatted A for one Resource, and formatted B for another. I'll use a name for an example.

Accessor of fullName

Resource A - John Doe

Resource B - john_doe

Is this correct?

Also for large scale applications, wouldn't Resources start to get a bit bloated after a while? For example, say you want the User formatted a certain way for 10 different pages, so you'd have 10 different Resources for each?

rodrigo.pedra's avatar

Well that is up to your app requirements.

If this 10 different pages are just consuming the data from the Backend and should not, or cannot, do any formatting on how they present the data, so one option is to have 10 different resources that provide the data as intended for each page.

But in general the frontend that presents the data have some flexibility over on how to present/format the data, so maybe this won't be needed.

In my apps I generally use different resources when consuming frontend needs data in different contexts, for example, maybe for an external API I won't send some fields, and for the regular in-house app I will add others, so I would have 2 different resources for theses contexts. But also I can have more in cases like retrieving data to fill an options dropdown where I just need a key and a label.

So it is up to your app requirements and the restrictions you have on the frontend on how much it can change the data on display.

Either way in the case you choose not to use resources, you would need 10 different accessors to present the same piece of data in 10 different ways for 10 different pages. In that scenario you would have to deal with 10 different method's name in the same class. I personally think, in that extreme scenario that it is easier - if the data need to leave the backend formatted and cannot be changed by the frontend - to have 10 different resources classes so when you are working on a class you have the context very clear and each class is very focused to serve a single purpose. But that is a personal preference, in the end of the day you should choose the approach that better fits your project's requirements and is easier for you, and your team, to reason about and maintain in the long run.

Hope it helps.

3 likes

Please or to participate in this conversation.