Laravel 13 Demo: JSON:API + Spatie Query Builder + Scramble API Docs

Hello guys, today I will show you a demo of Laravel API in a modern way with Laravel 13 with three different packages or techniques combined. So first JSON API specification which is now native in Laravel 13 but also combined with package query builder from spotty for filtering and also scramble for the dogs and this is the result of those docs and why specifically this setup it was endorsed by Taylor Otwell at Laracon EU. Let's listen. So this is the video and when presenting JSON API on stage, Taylor said this. Um, you can also pair this with a couple cool packages in the Laravel ecosystem. One is from Spot. It's called Laravel Query Builder that can read these JSON API URLs and build queries for you. And you can also use uh a package from the Scramble team to generate open API documentation for your API and generate docs. So yeah, you heard the man. Let's see it in action. But first, what is JSON API specification and why should you care about it? So, this is not a Laravel thing. It was adopted into Laravel technically in the version 12 something in the minor later versions but officially announced in Laravel 13 and I will show you how it works in Laravel in a minute. But the main thing is the format returned for example from get request here and the format and the keys and the structure of that return is exactly that specification which makes it predictable for any front- end client or mobile client or whatever is on the front end that can work with JSON API specification which is widely known standard and then they don't need to make any transformations or any weird modifications of the data because JSON API response comes right away with Laravel. So let's see a few things that are specific for JSON API compared to the alternative like you would return the JSON without that standard. So first we have the data wrapper. This is from Laravel Eloquent API resources. This is not really new. Then ID is string not integer. This is by specification. Then also type must be present which type of resource it is. Then the fields are wrapped into attributes. So the main fields related to this eloquent model you're returning. And as you can see here, there are no foreign keys, no relationships because they are elsewhere specific relationships section. And here you return all the relationships which are not related or not included rather in the database table or resource of the main thing which is a book. So author is separate and also even author is returned with data ID and type. This is also specific format with JSON API but you may also return the full relationship data with this included and then attributes for the author and then that itself as you can see the structure is the same as you would return a book. So id type attributes and then some meta data which is links and meta for pagionation and for any more global data you may want to return in addition to the main object. So yeah quite a lot of pretty strict requirements by JSON API but again it allows the front end clients to parse it successfully without any weird modifications on their side. In other words, more predictability, which is one of the main things when working with APIs because the main problem with APIs that the front end and the back end kind of talk in different languages quite often. And then there are errors when parsing the data or when returning the data or both. So any kind of standard is a good thing here and JSON API is one of the widest known ones. And now if we take a look at the code how that specific API endpoint works. This is the show method of the controller API controller. And you have a few things to look at here. Query parameter this is for the documentation for scramble. We'll take a look at that in a minute. And query builder is from spotty query builder for filtering. But basically under the hood it's still eloquent query. So book first or fail. And then the main part for JSON API is book resource. It's eloquent resource but it extends JSON API resource not just JSON resource. The JSON resource the typical old way is commented out above. So before Laravel 13 or in case you don't want to use JSON API you would do specifically in the documentation make resource and this extend JSON resource and then you specify to array with whatever format you want to return. Now with JSON API resource the code here is shorter. You define things almost like properties and a few things on top. So in the documentation JSON API resources you make resource providing JSON API and then you fill in the properties. So this is exactly what we're doing here. We define the attributes. You saw that in the Postman response. Then you define the relationships and links and meta. And then Laravel takes care of everything under the hood. In the API response you saw a minute ago, you saw this parameter include author. So this comes from the package of spitequery builder. And if we remove that and repeat the same endpoint, you would see no attributes for relationships. That's the whole point of filtering. So JSON API resource defines the potential relationships you may want to return or may not. It's a bit similar to GraphQL where the user defines what they want to be returned. So this is the next thing I will show you is actually the filtering and in the composer. JSON you may see this package which powers query building. But let me actually show it to you in action what is possible to query to filter and stuff like that. So this is the endpoint for listing of the books not the show of books but all the books. So ID 3, ID 2 and others you see for every book some data and then you may see in stock true for example in stock true and in stock true for everything. But for example if we scroll down ID 15 in stock false let's add a filter for that. So add a parameter filter in stock with array and true and then ID5 should not be seen. Yeah as you can see ID 13 and then ID 16. So basically only the records with in stock true. Next let's filter by title. For example, let's copy some word from some title and change title to this and this will perform the search. So we go up and we see that specific record ID 16 and then also a few more books with that specific Latin word. This is fake data. But yeah, this is how you query by partial string in the field. Also, you may filter by integer records with more or less operations. Like for example, filter price. So if the price is 45, let's make it lower than this. So we have equals and then less than 45. We launch and we will see books with only lower price than this. And you can even filter by scope. For example, scope genre is a book eloquent model scope. And you can do something like this. Gen genre equals the name for example fantasy we have that in the database and we will have some records with that genre from the database. So you can use eloquent scope automatically in the filter. This is again by spotty query builder package and then you can combine a lot of things in this URL query. So filter then another filter then another filter then there's also sort by dash price means descending and then what to include and if you send this so the price filter is lower than 30 but then sorted by price descending so 28 and the next one is 23 and so on and then we also include the author relationship and generous as expected here. So all of that is defined in a few places here. So if we take a look at index. So we have query builder for the package. Basically you provide eloquent model and you add query builder on top. And then you define what do you allow to filter by. This is for security thing. So not everything is possible to filter by and in some cases you may provide the exact. In some cases the scope here as you can see also custom callback also trashed also there are different filter operators. So for example there's dynamic equal and so on. You can see that on screen now. So this is what do you allow to filter by also allow sorts also allowed includes allowed fields and default sort as well. And then after all that defined, you return just book resource collection and that book resource is JSON API resource. So it's kind of like a team effort between JSON API resource standard and then spotty query builder on top of that and Laravel ties them together. And now the third part of that project defined by Taylor is the API documentation provided by this package called Scramble. Let me zoom that in a bit. Open API documentation generator from the code and some properties. You saw some of them in the code and let's browse around and see what we have here. So you can browse endpoints. For example, books list all books. This is a zoomed in version. Let me zoom out to the original and then you have those query parameters listed of what is even possible. So you can send that documentation to your front- end clients or to mobile or front- end developers including some response example and request sample and stuff like that. For example, if we click on create a new book, the request body also has validation rules. And also even in the sample request, those values are automatically generated. The package is trying to generate the correct values. And it even has a button send API request. I haven't actually tried it, but let's see. Created. Was it successful? Did it create the actual record? It seems so. So, ID of the book 51. Let's take a look at the database. So, we have the books table and yeah, the Great Gatsby is in the database. So, from the documentation, you can try out the API. Of course, you need to be careful with that with some fake or dummy database, I guess. But yeah, it is possible. And the thing is I didn't write any single code in here for this page. It's all in the package which is in composer JSON like this. And again you define the things in the controller in this case like this query parameter and others also you add some dog block comments. Some of that is optional. You may define only what you want to see in the docs. And by the way what I didn't show how that code would look without spotty package. I had that commented out. So if you want to have request filled and request has, you would have a lot of if statements without the package. So this is the main benefit. Okay, let's get back to the docs. So the result of all those parameters and properties and everything is the URL of docs. You saw that already /doc/appi, but also there's docs API.json where you can see open API 3.1.0. And this is a huge JSON file with all the details. So this is generated automatically. You don't need to have that file anywhere. So you cannot find it in the public or anywhere. It's just the route or in fact two routes. We can see in the documentation when scramble is installed. Two routes are added which means that those files are generated on the fly. If I understand correctly, I didn't find any artisan command something like generate docs or something. getting started. It's about routes resolution. It's about authorization, but basically it's all automatic. So yeah, all of that combined together is a great combination in my opinion. JSON API filtering with spotty package and then documentation with scramble. And with that JSON API more official in Laravel 13, I also updated my course on Laravel daily. I'm going through updating all courses to Laravel 13. So API from scratch is also updated with JSON API and JSON standards in general as a lesson and also at the end for each course. I decided to have AI skill included in pretty much every course that I will update. So I imagine a lot of people will not want to watch the course for one hour or two hours or read everything but they would want to have the lessons applied in their code bases. Right? So I created a skill for example in this case it's Laravel daily API audit which would basically check your codebase for recommendations or my personal preferences from that course from all the lessons. So you would get something like this recommendation for database transaction in this case or rate limiting or something with API. So if you want to get that skill or watch some of the lessons in that Laravel API course I will link that in the description below. And back to the original topic, what do you guys think of this demo and of JSON API in general? Would you choose those three specific tools, JSON API, Sparty, and Scramble? Or do you prefer some other packages or other combinations? Let's discuss in the comments below. That's it for this time and see you guys in other