Chapter 6. Illuminating RESTful Web Services with Lumen
So far, we have created a very basic RESTful web service in Core PHP and identified flaws regarding design and security. We have also seen that to make things better we don't need to create everything from scratch. In fact, using open source code that is time tested makes more sense, to build better web services based on cleaner code.
In the last chapter, we have seen that Composer is a dependency manager for PHP projects. In this chapter, we will use an open source micro-framework to write RESTful web services. We will do the same work in an open source micro-framework that is in active development, time tested and well known in PHP community. The reason for using a framework instead of few components is that a proper framework can make a good structure of our code, and it comes with some basic required components. The micro-framework we have chosen is Lumen, a micro-framework version of the full-stack framework Laravel.
Here is what...
Lumen is a micro-framework version of the full-stack framework Laravel. In the PHP community, Laravel is a very well-known framework. So by using Lumen, we can always our project to Laravel and start using its full-stack capabilities if we have to.
Every thing has a cost. We chose a micro-framework of a full-stack framework, because although a full-stack framework provides more features, to have those features it has to load more stuff. So provide the luxury of more features, a full-stack framework has to compromise a bit on performance as compared to a micro-framework. The micro-framework on the other hand, lets go of some features which are not required for building web services like views and so on, which makes it faster.
Lumen is not the only micro-framework in the PHP community. So why Lumen? There are three reasons for that:
- Lumen is micro-framework of Laravel, so with a little effort we can always convert it into Laravel and utilize...
To install Lumen, if you have composer installed simply run this:
composer create-project --prefer-dist laravel/lumen blog
This will create a directory named blog which has the Lumen installation in it. In case you find any difficulty, see the Lumen installation docs here: https://lumen.laravel.com/docs/5.4.
I suggest that after installation, you go and look at the directory structure of this Lumen project named blog, as it will make more sense when we will be performing different tasks.
If you look in the installation directory we installed Lumen, in our case it was blog, you will see a .env file. Lumen keeps configurations in the .env file. You can see there is an option APP_KEY= if this is yet set in the .env file, set it. This just needs to be set to a random string that has a 32 character length.
Note
As .env file starts with a dot, in Linux or Mac, this file may be hidden. In order to see this file, you need to see hidden files as well.
And then, to run Lumen...
We need to set up our for the blog. In fact, we already did set this up in Chapter 3, Creating Restful Endpoints. We can use that database here as well. In fact, we will have the same DB structure, so we can easily use the same DB, but this is not recommended. In Lumen, we use migrations to create DB structure. It is not mandatory but it is useful so you can write migration once and use it to create DB structure anywhere. This purpose can be served by SQL files but the beauty of migration is that it works across different RDBMS as well. So create a DB manually, and name it blog. Now, we will write migration for structure.
To create migration files in Lumen, we can use this in the blog directory to create file:
php artisan make:migration create_users_table
You will see something similar to this:
Created Migration: 2017_06_23_180043_create_users_table
and a file with this name will be created in the /blog/database/migrations directory. In this file,...
Writing RESTful web service endpoints
Now, it is time to actually start writing the endpoints that we discussed in Chapter 1, RESTful Web Services, Introduction and Motivation, and wrote in plain Vanilla PHP in Chapter 3, Creating Restful Endpoints. So let's do that.
As it has a Controller and Model layer, we will writing API from the Controller layer which will serve different endpoints. For the first controller, what we are going to write is PostController.
Writing the first controller
Technically, this is not the first controller, as Lumen comes with 2 which you can find in the /<our blog project path>/app/Http/Controllers/ directory. But this is our first controller that we are going to write. In Laravel (the big brother of Lumen), we don't need to go and create a controller there are commands for that, but for Lumen those commands are not available. As these commands are not mandatory but very handy, it is better if we make those commands available.
To use the extra features that...
Controller Implementation
Let's first add proper code in the PostControllerindex() method that will return actual data. But to see data coming in response, it is better to insert some dummy data in the users, posts and tables. A better way to do this is to write seeds for that. However, if you don't want to look into how to write seeds then you can insert it manually for now.
Here is an implementation of the index() method:
public function index(\App\Post $post)
{
return $post->paginate(20);
}Here, paginate(20) means that it will return a paginated result with the limit of 20. And as you can see, we have used dependency injection to get the Post object. This is something that we have already discussed in this chapter.
Similarly, we will have PostController other methods implemented here. This is what the PostController code will look like:
<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
class PostController extends Controller
{
public function __construct...
Are we done with making Controllers that serves RESTful resources endpoints? Actually no, we have missed many things. We just created basic RESTful web service, which can work just to give you an idea of how we can make it using Lumen, but we have missed many things. So, let's look at them and do them one by one.
Validation and negative cases?
First, we are only with positive cases: that means are not considering what happens if the request is not according to our assumption. What if the user is sending data with the wrong method? What if a doesn't exist with the ID that the user is passing on?
In short, we are not yet handling all that, but there are things that is handling for us already.
If you try to hit endpoint URLs, http://localhost:8000/api/posts/1 with the POST method, then, it is an invalid method. On those URLs, we can only send a request with GET, PUT or PATCH. With GET, it will trigger the PostControllershow() method while PUT or PATCH will trigger the update...
Till now, we have created RESTful web services endpoints in a micro-framework named Lumen. We created migrations, models and routes. I implemented PostController but left CommentController implementation for you. So, as we can see that lot of problems that we discussed related to implementation in Chapter 3, Creating Restful Endpoints, are solved already because of using a framework. And we are able to solve many other problems very easily. So, using the right framework and packages, we are able to work much faster.
We have also identified some missing elements, including user authentication. We will solve them in the next chapter. In the next chapter, we will improve our work from the code aspect as well.
Note
In this chapter, we were mostly working with Lumen. We looked at it but we were trying to proceed to make our API and so we were not able to see each and every part of Lumen and its code in detail. So, it is a good idea to see Lumen's documentation: https://lumen.laravel.com...
