RFC - Formatting of API endpoints about code-standards

[AdamHutchison]

Lets just sack it off and use graphql .....

[craigsansam]

So after the office debate our revised stance is as follows:

"Generally we use either Eloquent Resources, Fractal or GraphQL when developing APIs. The technical implementation varies from project to project and is decided upon by the lead developer/developers working on the project - taking into account the scope and complexity of the project and required endpoints."

[AdamHutchison]

Generally we use Fractal's DataArraySerializer
What do people think about starting to use laravel resources where we can? For me it makes more sense to utilise what's built into laravel rather than pulling in a package to achieve the same thing. And they're ridiculously simple to use. This would also help us consistently deliver endpoints in the same json format.

[JBonwick]

I personally do think so given the amount I use it- I did start to use Laravel resource on CG but found I needed the includes relatively early on.

I think the best example of its use case is the difference between an index and show endpoint. On the index, the user may only receive a top level of data then on show they get all the included data. Also means if the data is required on an index call it can be pulled in.

[samboylett]

TBH I'm fine with using multiple requests and never using includes. It keeps things RESTful, which is the point really. If we need lots of different models in one request then use GraphQL!

[spamoom]

TL;DR - Fractal.

[craigsansam]

@Juddling I did start documenting our API Build Guidelines/Best Practices a while ago - If you like I can port these over to the code-standards and we can review?

https://docs.google.com/document/d/1l-sSP87Op9XKfwcA4vhY9_jBrE3_levIHKIxUeJIVyA/edit?usp=sharing

[craigsansam]

I am going to close this RFC on Friday 22nd and add the outcomes to the coding standards.

[craigsansam]

Just had a quick look at the docs for Eloquent API Resources and they look pretty much identical to the way we've implemented Fractal which is great.

I can't find anything in the docs about optional includes?

Edit Here's a link to the relevant section of the Fractal docs if anyone is unsure what I mean by optional includes - https://fractal.thephpleague.com/transformers/#including-data

[JBonwick]

Laravel resources can't do includes, i've been using Laravel Fractal recently and it is all the goodness of fractal with extra support.

Example:
return fractal($books, new BookTransformer())->respond();

And for includes there are 2 options
return fractal($books, new BookTransformer())->includeAuthors->respond();
or
return fractal($books, new BookTransformer())->includes(['authors'])->respond();

[AdamHutchison]

No I don't think there is anything like that for api resources @craigsansam. Do you guys use that feature often? I can honestly say that I've never felt like I've needed it.

[craigsansam]

It comes in quite handy for adding relationship data that isn't in the response by default - for example, a users groups.

I think Mobile and Frontend benefit from it more - it's just something that's been added by default a lot of the time

[AdamHutchison]

Do you think it's worth pulling in the package for? I think this will probably be something that we decide on a project by project basis. I can see the benefit of the feature.

[craigsansam]

I'm not against having both - it could be the Laravel/Lumen-esque split?

Simple APIs - use Eloquent API Resources
Complex APIs - use Fractal (or Laravel Fractal)

Obviously we'd just need to define what constitutes a simple and complex API

[AdamHutchison]

I think conditionally adding relations could be achieved easily using the when method on resources https://laravel.com/docs/5.8/eloquent-resources#conditional-attributes

'authors' => $this->when(request()->input('authors'), $this->authors),

[JBonwick]

The resources syntax starts to get messy if you want the include to return another transformer (haven't tested but i assume the following works?)
'authors' => $this->when(request()->input('authors'), AuthorResource::collect($this->authors)),

That to me is where fractal includes are best suited but that would also then fit nicely into the simple/complex divide and i'd be happy to support both being used.

[craigsansam]

To mimic the functionality of the fractal include= query string, we're looking at something more like:

	'authors' => $this->when(
		in_array('authors', explode(',', request()->input('include'))),
		AuthorResource::collect($this->authors)
	),

We could always make a helper for it? But then are we reinventing the wheel? Not sure if there's anything else we use in Fractal?

[JBonwick]

On Moonlight we took the includes further- we had requests such as
api/screenings/event/3/film/1?include=event.films.upcoming_screenings
which was used to get the upcoming screenings of other films at the same event. You'd have to break that into a separate endpoints (which probably would've made sense in this example) but it's that multilevel includes that resources can't compete with.

[AdamHutchison]

I think multilevel includes might encourage the endpoints to veer away from REST tbh

[spamoom]

To re-repeat what has been said.

Eloquent resources are great as they ship with Laravel but they are missing relation includes.

Fractal (laravel-fractal) makes things much easier and the transformers are easier to define and read (especially relations)

Graph - read only.

[AdamHutchison]

I've been doing some research and it's quite easy to replicate the relation includes in laravel api resources. If anyones interested, give me a shout and I'll show you.