API Platform for Laravel: My First Impression

- I have tried out the API platform for Laravel and I will share my opinion. In this video I have tried to generate the API for an existing mini CRM project which does not have API. - In the video, they talk about deprecating resources instead of versioning and the use of eloquent API resources. However, the latter feature is not powered by API platform.

Hello guys, recently I saw this retweet by Taylor Otwell introducing API platform for Laravel. In this video I will show you what API platform is. I've tried it out for Laravel and I will share my opinion. Is it worth to use? In short, it's a platform to generate your API for existing or new Laravel project. Historically, API platform has been a tool for Symfony framework. Now it is also supporting Laravel. Let's take a look if we go to the official homepage of apiplatform.com now we have two arrows, Laravel or Symfony. And Laravel is introduced with a Lambo obviously. And in this video I've tried to generate the API for existing mini CRM project which does not have API at all. And by the end of this video we'll have slash API which is of course Lambo again which is swagger UI powered documentation with one crud powered by API generated with API platform API platform is available for Laravel as Laravel package. If we go through the Docs API platform for laravel projects to install is just composer require the package and PHP artisan install. That's it. So I did behind the scenes, installed it into my existing Laravel project and then I can generate API crud for one of eloquent models. The documentation shows the full process of making model with migration and then this is the main thing. So instead of running Laravel artisan commands like PHP artisan install API, PHP artisan make controller for the API routes API file, all you need to do is define this in your model. So here I am in my client model and all I need to do on top API resource from that API platform and this is on top here in the use section. And then API platform automatically generates that API page. So we can go to slash API and it's already ready for us. All the crud for API clients. So I didn't do any routes API change. I don't have any laravel controllers for the API. Specifically I just exposed the eloquent model for the API platform. And this is powered by Swagger Ui as I mentioned, which allows you to try out the API right here in the browser so we can go API clients, click, try it out and then execute and it will actually execute the API call. And this is our result 200 status code. Let me zoom that in. Probably response body looks like this. So this is the JSON response and this is the database data. So the fields are available automatically and camel cased if I don't specify anything else. Now the structure of this returned response is powered by a standard called JSON LD. You can read more about it in the JSON LD specification or on Wikipedia. Here I've opened that page. Basically it's called JSON for linking data, and that linking data can be seen, for example, like this. So chose the endpoint URL for that specific object. Also, you can launch the same thing in any of your API clients. For example, I'm using Postman here and I send and I get the same here in the postman. And this is where we see the first limit of that API platform. This is an honest review by myself, just trying it out. I'm not biased here, I'm just sharing my opinion. So my personal opinion was first, what is that member? And how can I customize that? Because I was used to data in Laravel API resources. Then how do I use API resources? Because again I was used to that. More questions like how do I hide the fields if I want to hide them? Or how do I do versioning like v one? And some of those questions are answered in the docs and some of them are not. So this is the general thing. While using laravel packages, or any packages in fact, especially the ones that power your core architectural features, they look good on the surface, but when you'll dig deeper, then you bump into limitations, and then some of them you can overcome, some of them you can't. So my general advice kind of along the way is to read the docs of the tool and the framework and the package that you choose to use for something fundamental. Read the full docs. Read the second part of the docs, not just the shiny scenario. So some of those things I mentioned can be customizable pretty easily. For example, the fields in the client model, we can use the same feature as Laravel, which is hidden. You can provide hidden array of fields, for example created ad, you can hide it. And now if we run the same thing, for example in the postman, we don't see created ad here anymore. So this is what does work. What doesn't work is I didn't find any documentation about how to change that member thing. Maybe it's my issue, maybe it's skill issue, maybe it's reading the docs issue. At least it wasn't mentioned in the Laravel Docs for API platform. Maybe for some cases we need to dig deeper into core API platform documentation, or symfony or stuff like that. So I didn't check that part of the docs. Maybe it is customizable then same with versioning. How do I add v one here or v two? The answer in the docs of that API platform is that you should use deprecating resources instead of versioning. It is considered a best practice regarding web API development to apply the evolution strategy, which means the same API endpoints should work for old and new clients to avoid clients to change the endpoint. Because often it is hard to force all the clients like your mobile clients or web clients to start using the new v two API. So this feature directly is not powered by API platform. So you cannot easily do something like route prefix v one or something like that. Also in eloquent I was expecting for attributes to work because quite often the returned API response is different from eloquent fields. And for that I typically use eloquent API resources like this, so I can customize the returned fields or return only some of them or change something like this. So this is kind of a standard laravel way to work with API returns. But OpenaPi platform seems to not use eloquent API resources at all. It uses eloquent models and this is where we need to stop for a second. This is pointless from the future. After editing this video, I realized that in this video I called API platform OpenAPI platform four times. Not sure why it happened kind of automatically, so it was too hard to edit that out. So I will just include this notice that the name is API platform. OpenaPi is a totally different thing is OpenAPI standard specification, and you can google that separately. But in this video we're talking about API platform. Now back to the video. So even though the API resource exists, it isn't taken into account at all. And as for accessors, for eloquent in the issues of the API platform, I found this with Laravel eloquent accessors. So people report some issues with it. But let's return to our shiny scenario. If you need just a simple API without much configuration and customization, which does work, and let's see what else do we have under the hood? What features are available in OpenAPi platform? For example, you can add filters easily just by providing another PHP attribute in the model. I will paste it from the docs query parameter, for example contact name and then which filter it is equals there are other filters. And now for refresh that page of API in our get API clients in try it out, we have another parameter that we can filter by, for example John. We execute and then the URL contains that contact name John and if there are members with John that would be returned here. So for example, if we try the record that does exist by contact name, I execute and that member should be returned here in the results. So that's easy filtering and you can provide which columns to filter by. Also post request does work as well. So if we close that and there's post API clients, you can also try it out with request body suggested to you by contact name and something else. So ABCD and you execute the returned result is a response with the data of that new client. Now what about validation? API platform does support form requests by Laravel, but in a bit weird way. So in the web version of that project, in the client controller, I do have store client request with validation rules and I can use that form request for the API as well. And if we follow the official documentation, it suggests to make a request and then the documentation says that if the standard Laravel conventions are followed, then it is automatically detecting that form request class. But in my case that form request was not detected. Maybe because I'm using store client request instead of just client request. Because in this documentation case the request class is called book form request. So maybe I should have client form request and the same for store and update, I'm assuming that. But in any case I can enable that API resource validation with form request by assigning a parameter to API resource rules come from store client request class, which is here on top as well. So then if I try that request again but without for example missing contact name or something, I execute and the result should be four, two, two validation contact name field is required. If I don't provide that validation rule, let's try it out, I will show the difference. So if we execute that again, we will then get 500 internal server error because the validation doesn't work and then it tries to execute the SQL query which then returns the 500. So yeah, another example of Laravel feature supported by OpenAPI platform, but not in a standard intuitive way you would expect. If you go to the table of contents of the official docs, there are more features like GraphQL for example pagination, authentication and authorization. So it does use policies and it does use sanctum. And also there are tools both from OpenAPI platform in general and specific to Laravel. For example, using the JavaScript tool there's react admin admin panel generated as well as that swagger UI power documentation. This is built with material design and react admin. So you need to know react to be able to use it. But you can generate a, a simple admin panel for your clients non developers just with this API platform as well. So yeah, the question would I recommend that platform, or would I use it myself? At this moment, no. But this is a great starting point if the API platform authors do want to dive deeper into Laravel community because it's still a symphony project historically. And Kevin Dunglas when he announced the Laravel version during API platform conference recently, even that conference is full of symphony. So I found on Twitter Twitter that Celia's is sponsoring API platform Con and Senseiolabs, creator of Symfony are also there. So for now it feels like the first platform expansion into Laravel with just scratching the surface. Maybe my impression is wrong. We can discuss in the comments below. Maybe the platform would adopt more Laravel features in the future. Or maybe there would be better documented for laravel developers which core features of the platform we would be able to use to customize laravel stuff in more familiar way to us laravel developers. And if you do prefer the laravel way of building stuff instead of using platforms like OpenaPI, I have a special course for Laravel daily members how to build Laravel API from scratch, updated to Laravel Eleven, with a lot of laravel centric features like API resources and versioning and observers and stuff like that. So I will link that course in the description below. That's it for this time and see you guys in other videos.