[5.5] API Responses #19449

themsaid · 2017-06-01T21:52:20Z

This PR Introduces a trait you can use on a Responsable:

class UserApiResponse implements Responsable
{
    use isApiResponse;

    public function __construct($resource)
    {
        $this->resource = $resource;
    }

    public function transformResource($resource)
    {
        return [
            'name' => $resource->name,
            'email' => $resource->email,
        ];
    }
}

The trait needs a $resource property to exist on your Responsable object, using this convention it's going to create a response for you based on the type of object you pass (Resource, Collection, Paginator), you have to implement a transformResource method to tell Laravel how to transform a single resource instance for the API.

Now in your controller you can return any of the following:

return new UserApiResponse(User::find(1));

return new UserApiResponse(User::paginate(15));

return new UserApiResponse(User::find([1,2]));

// You can pass a status code using:
return (new UserApiResponse($user))->withStatus(201);

// You can also do:
return UserApiResponse::with($user)->withStatus(201)->withMeta(['valid' => true]);

The responses will look like the following:

For a single resource:

{
  "data": {
    "name": "Prof. Alfonzo Schulist DDS",
    "email": "[email protected]"
  },
  "meta": {
    "value": true
  },
}

For when you pass a paginator:

{
    "data": [
        {
            "name": "Prof. Alfonzo Schulist DDS",
            "email": "[email protected]"
        },
        {
            "name": "Prof. Oma Armstrong PhD",
            "email": "[email protected]"
        }
    ],
    "meta": {
       "value": true,
        "current_page": 1,
        "from": 1,
        "last_page": 50,
        "next_page_url": "http://laravelnext.dev/controller?page=2",
        "path": "http://laravelnext.dev/controller",
        "per_page": 2,
        "prev_page_url": null,
        "to": 2,
        "total": 100
    }
}

For when you pass a collection:

{
    "data": [
        {
            "name": "Prof. Alfonzo Schulist DDS",
            "email": "[email protected]"
        },
        {
            "name": "Prof. Oma Armstrong PhD",
            "email": "[email protected]"
        }
    ],
    "meta": {
        "value": true
     },
}

arcanedev-maroc · 2017-06-01T22:56:00Z

Hi @themsaid, can you change the metadata name to meta ?

Keep up the good work 👍

arcanedev-maroc · 2017-06-01T23:07:17Z

Hi again,

can you check the paginator response in your description:

{
    "data": [
        {
            "name": "Prof. Alfonzo Schulist DDS",
            "email": "[email protected]"
        },
        {
            "name": "Prof. Oma Armstrong PhD",
            "email": "[email protected]"
        }
    ],
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 50,
        "next_page_url": "http://laravelnext.dev/controller?page=2",
        "path": "http://laravelnext.dev/controller",
        "per_page": 2,
        "prev_page_url": null,
        "to": 2,
        "total": 100
    }
}

The last_page must be equals to 2 and the per_page equals to 50 (also the to value).

I know this is just an example but i'm confused to process it 😜

EDIT: NVM, otherwise you need to show 50 records in the data

yajra · 2017-06-02T03:55:42Z

src/Illuminate/Http/ApiResponseTrait.php

+    {
+        if ($object instanceof Collection) {
+            return [
+                'data' => $this->user->map([$this, 'transformResource']),


I think this should be $object and not $this->user? Same applies below.

sixlive · 2017-06-02T13:58:21Z

Would love to see a static factory especially with the withStatus() method.

return UserApiResponse::create(User::find(1))->withStatus(201);

I would also get some usage about adding misc meta. So maybe a ->withMeta($metaArray) or ->withMeta($key, $value) that would be merged in with the patination data if that exists.

Any thoughts on making the pagination meta its own key?

{
  "data": [
    {
      "name": "Prof. Alfonzo Schulist DDS",
      "email": "[email protected]"
    },
    {
      "name": "Prof. Oma Armstrong PhD",
      "email": "[email protected]"
    }
  ],
  "meta": {
    "pagination": {
      "current_page": 1,
      "from": 1,
      "last_page": 50,
      "next_page_url": "http://laravelnext.dev/controller?page=2",
      "path": "http://laravelnext.dev/controller",
      "per_page": 2,
      "prev_page_url": null,
      "to": 2,
      "total": 100
    }
  }
}

themsaid · 2017-06-02T14:11:00Z

Added a ::with() static constructor as well as a withMeta() method.

return UserApiResponse::with(User::paginate(5))->withMeta(['test' => 123]);

JacobBennett · 2017-06-03T20:44:54Z

This looks like an awesome addition! Would help a ton to be able to standardize the format that we use to return api data to the front end. With that in mind, are there any thoughts regarding a standard format when returning errors for api requests? For instance if I use a User::findOrFail(1), currently that will generate a HTML response instead of a JSON response. Maybe if using a Responsable, we can assume they want a JSON error instead and handle it appropriately?

Not sure if this is the correct venue for discussing it but figured I would give it a mention.

sixlive · 2017-06-03T20:53:34Z

@JacobBennett I typically do this in the global exception handler since most of those types of exceptions you will want to handle in the same way. Also, you will want to look at the way 5.5 is going to render exceptions now, you might be able to bake it into that.

themsaid · 2017-06-03T23:11:26Z

@JacobBennett in 5.5 if your API call has a Accept: application/json header laravel will transform all exceptions to JSON:

{
    "message": "Exception message"
}

sixlive · 2017-06-04T00:11:12Z

Totally forgot to mention that. Would be nice if it would respond with JSON automatically if the route is an API route

arcanedev-maroc · 2017-06-04T00:38:42Z

@sixlive, in your API routes (or Controllers) should respond with:

return response()->json(...);

Or something similar.

This PR is just a helper to transform objects without using external packages like fractal or even using response()->json(...).

sixlive · 2017-06-04T00:41:21Z

Thanks! Well aware of what this PR is. Just making a side comment on global exception handling responses.

DanielDarrenJones · 2017-06-04T12:26:24Z

@sixlive This was added in a recent PR to fix for 5.5 #18732 and has been merged, the API should be standardised across Laravel going forward hopefully 👍

sixlive · 2017-06-04T13:11:44Z

@DanielDarrenJones Oh sweet! Thanks mate! Totally missed that one!

lkmadushan · 2017-06-04T14:27:20Z

Isn't it better to use class inheritance without using a trait. Something like,

ApiTransformer implements Responsable {
     ..
}
UserTransformer extends ApiTransformer {
    ...
}

Anyway it seems this is equivalent to league/fractal

JacobBennett · 2017-06-04T16:05:10Z

Thanks for the heads up on the JSON response stuff for exceptions @themsaid, looks like 5.5 has it covered!

antonkomarev · 2017-06-04T16:06:05Z

@lkmadushan you always could make your own class which will use trait under the hood.

tillkruss · 2017-06-04T21:47:07Z

src/Illuminate/Http/ApiResponseTrait.php

+use Illuminate\Database\Eloquent\Collection;
+use Illuminate\Pagination\AbstractPaginator;
+
+trait ApiResponseTrait


Could we call this something else? Like ApiResponse or RespondsToApiCall or something without the Trait suffix..

Agree with @tillkruss. Suggesting one more option: HasApiResponse

This trait actually describes what the class is, so IsApiResponse sounds good to me.

@JosephSilber option is the best one.

JosephSilber · 2017-06-04T21:25:12Z

src/Illuminate/Http/ApiResponseTrait.php

+     *
+     * @var array
+     */
+    public $metaData = [];


Metadata is a single word, and should therefor not be camelcased.

Can't agree with it because result will be displayed in meta array key.

JosephSilber · 2017-06-05T00:11:04Z

src/Illuminate/Http/ApiResponseTrait.php

+use Illuminate\Database\Eloquent\Collection;
+use Illuminate\Pagination\AbstractPaginator;
+
+trait ApiResponseTrait


This trait actually describes what the class is, so IsApiResponse sounds good to me.

lucasmichot · 2017-06-05T09:34:27Z

src/Illuminate/Http/ApiResponseTrait.php

+
+use InvalidArgumentException;
+use Illuminate\Database\Eloquent\Collection;
+use Illuminate\Pagination\AbstractPaginator;


Then we should also require "illuminate/database": "5.5.*" and "illuminate/pagination": "5.5.*" in Illuminate/Http/composer.json

lucasmichot · 2017-06-05T09:42:36Z

src/Illuminate/Http/ApiResponseTrait.php

+    /**
+     * Create an HTTP response that represents the object.
+     *
+     * @return \Illuminate\Http\Response


@return \Illuminate\Http\JsonResponse instead

lucasmichot · 2017-06-05T09:43:34Z

src/Illuminate/Http/ApiResponseTrait.php

+     * Create an HTTP response that represents the object.
+     *
+     * @return \Illuminate\Http\Response
+     * @throws InvalidArgumentException


Missing backslash => @throws \InvalidArgumentException

lucasmichot · 2017-06-05T09:46:38Z

Great @themsaid !

I think having withHeaders() and withOptions would be great too, so that we can use the headers and options values when returning the response:
return response()->json($this->transform(), $this->status, $this->headers, $this->options);

themsaid · 2017-06-05T10:07:05Z

Thanks @lucasmichot and @JosephSilber, applied the following changes:

Renamed to isApiResponse
Renamed metaData to metadata
Added illuminate/pagination to composer.json
Changed the import to look for support/collection instead of eloquent/collection
Added withHeaders
Added withEncodingOptions

lucasmichot · 2017-06-05T10:07:51Z

src/Illuminate/Http/composer.json

@@ -17,6 +17,7 @@
        "php": ">=7.0",
        "illuminate/session": "5.5.*",
        "illuminate/support": "5.5.*",
+        "illuminate/pagination": "5.5.*",


Should probably be sorted ;-)

JosephSilber · 2017-06-05T11:18:01Z

Shouldn't we use the ResponseTrait here?

lucasmichot · 2017-06-15T13:31:50Z

I share @adiachenko opinions on that, @taylorotwell
@themsaid, any chance to release this code as a package ?

themsaid · 2017-06-15T14:24:43Z

@taylorotwell said he'll think about it more, if he decided to not go for it then yes I think releasing it as a package would be nice :) Just hope this gets into the core since it's really simple but helps alot with creating responses.

DanielDarrenJones · 2017-06-15T14:29:22Z

I fully agree, JSON-API feels way to over spec for what 99% of people need.

Having something simple now would make such a huge improvement across the board for Laravel, is there a way the formatters could be pulled out to be configurable so if in the future it changes to JSON-API or another mapping it can be replaced by the user?

joselfonseca · 2017-06-27T21:08:15Z

This looks like what http://fractal.thephpleague.com does.

deleugpn · 2017-06-27T21:10:14Z

@joselfonseca I would go out on a limb here and say that 100% of people trying to PR API responses into Laravel have used and disliked Fractal.

DanielDarrenJones · 2017-06-27T21:12:00Z

@deleugpn Actually I really like fractal, especially when wrapped in https://github.com/spatie/laravel-fractal, that said it would be nice to have a unified global api response system in Laravel.

joselfonseca · 2017-06-27T21:12:50Z

@deleugpn Interesting, I find it quite good myself. Then again having something in Core would be nicer.

adiachenko · 2017-06-28T10:22:23Z

@DanielDarrenJones Well, Fractal (kinda) does the job, but it's very awkward. Among other things:

it causes severe N+1 problems unless you are very careful about what you're doing and explicitly check whether relationship is loaded in Transformer's includes (which isn't even what suggested in the docs)
it performs complex query string parsing on each request
apparently, it has very rigid serializers. Say you namespace your response under data property, this will automatically propagate to relationships based on how Serialize interface is constructed which may not be what you want
it claims to offer multiple serializers out of the box, but it is apparently built with DataArraySerializer in mind and everything else is just an extra (btw, the one for JSON API won't work with clients that expect spec compliance like ember-data)
etc.

In short, there's no smoke without fire. Otherwise, we'll all be using Fractal by now instead of trying to push a similar solution into the core.

arcanedev-maroc · 2017-08-17T15:30:21Z

Praise the 🌞 \[T]/

taylorotwell · 2017-08-18T12:56:17Z

Something that would help me in this thread are answers to this question: what are we trying to solve? At the end of the day, implementations seems to boil down to something like this:

function transformPost($post)
{
    return [...];
}

function transformUser($user)
{
    return [...];
}

Everytime I start hacking on it a bit I come back to the core fact that we are just giving you a fancy way to declare a plain PHP function that returns an array. Is that all we're trying to do? Does everyone agree with that?

themsaid · 2017-08-18T13:24:10Z

@taylorotwell basically yes, a way to convert an object to a PHP array to finally be converted to JSON.

We're also trying to bring the ability to automatically convert a Collection of objects or a pagination to a JSON format, where objects inside those collections are transformed using the toArray function we're adding in this feature.

taylorotwell · 2017-08-18T13:26:29Z

And the main problem with using toArray on the model to do this is because you have multiple API versions? Or is there some other reason?

DanielDarrenJones · 2017-08-18T13:26:41Z

@taylorotwell

The main reason for transformers in my opinion is to decouple the underlying attribute names or database table names from the API response, doing so means we can change the underlying data structure while still keeping consistencies for users.

It also gives us a chance to cast the type explicitly before it is transformed to JSON, this has its uses from time to time.

Having a base transformation structure of the model allows us to pull that in a different response templates and transform to standard API response formats much like JSONAPI or similar.

I think ultimately I am looking for something very similar to https://github.com/spatie/laravel-fractal, I want an easy way to model my API responses.

I think over the last year and a half especially since Laravel has become so close to Vue we have seen a strong shift towards API driven development and for Laravel to fully embrace this we need the tools to do it correctly.

arcanedev-maroc · 2017-08-18T13:27:04Z

I think the main reason of this feature is to have something similar to thephpleague/fractal out of the box.

Creating a plain PHP function doesn't seems as an Eloquent way to work with.

When creating a Transformer class, you can apply it to a Model, Eloquent Collection or a Pagination object.

Instead of using an external library, i think laravel already has more than 90% of features to handle the json responses (especially the transform method in Collection class).

Adding this feature is like adding the cherry on the cake.

UPDATE:
I use also the Nested Transformers:
UserWithPostsTransformer > UserTransformer (user model) + PostTransformer (posts relation)

themsaid · 2017-08-18T13:28:58Z

@taylorotwell toArray could be used it tests or other places in the code, it's useful to have a function that's only purpose is to convert a resource to an API format, maybe do conversions, change float to integer, append strings, hide parts of a secret *******9876, etc...

taylorotwell · 2017-08-18T13:29:35Z

OK thanks for your responses.

lkmadushan · 2017-08-18T13:37:09Z

Is there any benefit using this instead of league/fractal?

taylorotwell · 2017-08-18T13:55:43Z

@lkmadushan someone tried to answer that like 6 comments up.

lkmadushan · 2017-08-18T14:06:57Z

@taylorotwell yeah. see those comments. but didn't see any special difference compared to league/fractal. it seems like we are doing same thing in different ways.

but It would be great if you can provide a JSON-API response format and a supported client for the frontend to consume JSON-API API service easily.

Aferz · 2017-08-18T14:28:16Z

For me, the main purpose of features like this is being able to respond to a request in a very specific way with very specific data with common resources.

With attributes like hidden, append, or with inside models, we are just being able to declare general behaviour to this model for the whole application. Despite this is not a big problem, with this configuration we are assuming that when we want to display an user, we always want to display them with the same attributes, and we all know this is not true for every scenario.

We are trying to use common resources (Models) for specific responses. That's why generic behaviours doesn't match very well when we are trying to do such specific/independent things.

Fractal does a very good work in this area, but it is extremely verbose for a framework like Laravel and I and many like me think it could be done better. (No pretending to offense to PHPLeague, of course)

That's why I opened a PR (time ago) trying to figure out what is the Laravelish way to accomplish such work #18502. Is a bit old, and I didn't know about recent Responsable interface, so it could be handled better now, but you get the basic idea.

deleugpn · 2017-08-18T16:40:43Z

@lkmadushan it's the same thing, but done right.

taylorotwell · 2017-08-21T02:06:28Z

@deleugpn I'm curious to hear your problems with Fractal.

antonkomarev · 2017-08-21T06:15:55Z

@lkmadushan JSON:API Server responses is a good thing to have out of the box, but JSON:API Client is task out of the Laravel scope. It's not a trivial job and there is no reason for the Laravel team to develop and maintain it.

deleugpn · 2017-08-21T15:19:51Z

@taylorotwell at first, it's not beginners-friendly. You have to opt for dingo/api or spatie/laravel-factral. Although spatie does provide a good support for it, it's still pretty verbose.

As you mentioned yourself in the thread, we're basically seeking model-to-array transformation layer. The amount of overhead just for that is too high through Factral.

Factral include functionality is actually a Pandora's box. You think it's making your life easy by offering relationship transformation, but you end up with (already mentioned) N+1 problem unless you're extremely careful with covering all your entry points to the layer.

At the end of the day, I think we're trying to have simple (and laravel-friendly) transformers for simple things.

taylorotwell · 2017-08-23T20:32:19Z

Done.

arcanedev-maroc · 2017-08-23T20:42:17Z

PR: #20710

yajra reviewed Jun 2, 2017

View reviewed changes

themsaid mentioned this pull request Jun 2, 2017

[Proposal] Standardise JSON Responses laravel/ideas#603

Closed

themsaid added 2 commits June 2, 2017 20:51

api responsables

d5f1994

code style

dcf8209

tillkruss reviewed Jun 4, 2017

View reviewed changes

JosephSilber reviewed Jun 5, 2017

View reviewed changes

lucasmichot reviewed Jun 5, 2017

View reviewed changes

themsaid added 2 commits June 5, 2017 12:09

multiple changes

273ee0a

update tests

40ab5e4

arcanedev-maroc mentioned this pull request Jun 27, 2017

Updating the Json Response Transformer ARCANEDEV/LaravelApiHelper#4

Merged

taylorotwell reopened this Aug 17, 2017

fix conflicts

f82962f

taylorotwell closed this Aug 23, 2017

[5.5] API Responses #19449

[5.5] API Responses #19449

Conversation

themsaid commented Jun 1, 2017 • edited Loading

arcanedev-maroc commented Jun 1, 2017

arcanedev-maroc commented Jun 1, 2017 • edited Loading

Choose a reason for hiding this comment

sixlive commented Jun 2, 2017

themsaid commented Jun 2, 2017

JacobBennett commented Jun 3, 2017

sixlive commented Jun 3, 2017

themsaid commented Jun 3, 2017

sixlive commented Jun 4, 2017

arcanedev-maroc commented Jun 4, 2017

sixlive commented Jun 4, 2017

DanielDarrenJones commented Jun 4, 2017

sixlive commented Jun 4, 2017

lkmadushan commented Jun 4, 2017

JacobBennett commented Jun 4, 2017

antonkomarev commented Jun 4, 2017

Choose a reason for hiding this comment

antonkomarev Jun 4, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

antonkomarev Jun 5, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lucasmichot Jun 5, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lucasmichot commented Jun 5, 2017

themsaid commented Jun 5, 2017

Choose a reason for hiding this comment

JosephSilber commented Jun 5, 2017

lucasmichot commented Jun 15, 2017

themsaid commented Jun 15, 2017 • edited Loading

DanielDarrenJones commented Jun 15, 2017

joselfonseca commented Jun 27, 2017

deleugpn commented Jun 27, 2017 • edited Loading

DanielDarrenJones commented Jun 27, 2017

joselfonseca commented Jun 27, 2017

adiachenko commented Jun 28, 2017 • edited Loading

arcanedev-maroc commented Aug 17, 2017 • edited Loading

taylorotwell commented Aug 18, 2017

themsaid commented Aug 18, 2017

taylorotwell commented Aug 18, 2017

DanielDarrenJones commented Aug 18, 2017 • edited Loading

arcanedev-maroc commented Aug 18, 2017 • edited Loading

themsaid commented Aug 18, 2017

taylorotwell commented Aug 18, 2017

lkmadushan commented Aug 18, 2017

taylorotwell commented Aug 18, 2017

lkmadushan commented Aug 18, 2017

Aferz commented Aug 18, 2017

deleugpn commented Aug 18, 2017

taylorotwell commented Aug 21, 2017

antonkomarev commented Aug 21, 2017 • edited Loading

deleugpn commented Aug 21, 2017

taylorotwell commented Aug 23, 2017

arcanedev-maroc commented Aug 23, 2017

themsaid commented Jun 1, 2017 •

edited

Loading

arcanedev-maroc commented Jun 1, 2017 •

edited

Loading

antonkomarev Jun 4, 2017 •

edited

Loading

antonkomarev Jun 5, 2017 •

edited

Loading

lucasmichot Jun 5, 2017 •

edited

Loading

themsaid commented Jun 15, 2017 •

edited

Loading

deleugpn commented Jun 27, 2017 •

edited

Loading

adiachenko commented Jun 28, 2017 •

edited

Loading

arcanedev-maroc commented Aug 17, 2017 •

edited

Loading

DanielDarrenJones commented Aug 18, 2017 •

edited

Loading

arcanedev-maroc commented Aug 18, 2017 •

edited

Loading

antonkomarev commented Aug 21, 2017 •

edited

Loading