Using API resources to display all petitions

- [Instructor] Let's work on a petition controller now. Open the PetitionController PHP file and let's see the index method. If we were building a web application, not an API, we would probably do something like this in our index methods. We would fetch all the petitions from the database and save it in the petition variable, and then pass them onto the view. However, when building an API, we don't pass data to the front end, we return JSON instead. And Laravel offers a very convenient way to structure the JSON data called API resources. API resources are templates that define the structure of JSON data returned in the response. They allow us to transform the data we send to the user. For example, we can hide some fields or add a computed field. When the user requests a petition, we get the data from the database, pass it through this template that we defined in the PetitionResource.php file, and this is what's going to be returned to the user. When a resource is created, it comes with a toArray method. This method has access to the whole request object which means we can customize and transform what will be returned by modifying the return statement. If we leave it as it is, all model attributes will be returned. However, let's say we only want to return the id, title, and the author. We would define these field like this, omitting the other attributes. In the written statement, we will define the id is $this->id, the title will be $this->title, and the author will be $this->author. When we are returning a list of resources, such as in the index method, we need to extend a collection resource instead. This has access to the already transformed data in the PetitionResource.php file and returns a collection. We will modify the return statement again and wrap the Collection in a data object. Data will be $this->collection. Now that we have prepared a API resource template, let's go back to our index method where we will list all resources, or in our case, petitions. Instead of returning the view, we can take our petitions, which have been saved in the petitions variable, pass them to the PetitionResource and call the collection method on the resource. Make sure you have imported a petition model and a PetitionResource at the top of the file. We can also remove the petitions variable and pass the petitions directly into the PetitionResource. In a standard web response, we would return a HTTP response which is what PhpStorm is expecting. We can change this DocBook return value to return anonymous resource collection instead. There are two ways to return a collection by calling the collection method under resource like we are doing right now, or by returning and new collection. Let's reset a new collection and view the output in the browser. If you are using PHP artisan serve, make sure it's running. Otherwise you won't be able to display the data in the browser. The URL is my local host/API/petitions as we define in the API.php file. As you can see, we have all 50 petitions that we created in the previous video. Notice that we are only seeing the ID, title and author like we defined in the PetitionsResource.php file and the JSON is wrapped in the data object which is really convenient. The reason for this is that sometimes we want to return other pieces of information along with the data such as some custom headers your API version and so on. You can attach these extra pieces of data inside a two array method on the petition collection like this. Let's go back to the PetitionCollection file and let's add for example, version, which could be 0.1.1 and the author, which will be me. If I go back to the browser and refresh scroll all the way down and here's the version and the author. This data will now be sent with every API response. However, if we restart our collection by calling the collection method on the petition of resource it will not return any additional metadata. Let me show you, let's go back to our index method in the petition controller. And instead of returning PetitionCollection we will return PetitionResource and call the collection method on it. Let me save the file, go back to the browser and refresh. If I scroll all the way down, you can see that the metadata is no longer there. So keep this in mind when returning collection this way, as for this course, I'll stick to returning and new collection. So let's revert our code back to what it was. Now that you know about a differences between these two approaches? You can choose to return your collection in any way that works for you and your project.