Building a REST API with Lumen
I recently developed an API with Laravel for a mini-project a couple of friends and I worked on. I decided to build another API but with Lumen instead, since it’s a far lighter and faster framework than Laravel.
Lumen is a micro-framework built on top of Laravel’s core components. Lumen utilizes a lot of familiar concepts from Laravel such as Eloquent, caching, routing, middleware and it’s service container. One major advantage of Lumen is it’s speed, as a result the framework is designed for building fast micro-services or APIs.
Though this tutorial is about Lumen, a simple understanding of how Laravel works is all you need to follow along.
Setting up Lumen
There are several ways you can set up Lumen locally. For the sake of this tutorial, we’ll be doing so via composer
. You can check out other ways to set up Lumen here.
From your terminal, run: composer create-project — prefer-dist laravel/lumen lumen_api
This will install Lumen and all it’s dependencies for you in the lumen_api
directory. Next, we’ll be renaming the.env.example
file located in the root
directory to .env
Lumen’s default cache
driver as at 5.4 is memcached,
but we won’t be needing that for this tutorial. However any of the following, array
database
and redis
are supported. Edit the .env
file and replace the default CACHE_DRIVER
and QUEUE_DRIVER
values with the following:
CACHE_DRIVER=array
QUEUE_DRIVER=database
To serve our project locally, we can make use of PHP’s built in server by running the following command:php -S localhost:8000 -t public
Visit localhost:8000
in your browser and you should see the following page.
What we’ll be building
We’ll be building a simple REST API that handles Create, Read, Update and Delete tasks for a product resource
. Let’s take a look at our endpoints
- GET /products — Fetch all product resource
- POST /products— Create a new product resource
- GET /product/{id} — Fetch a product resource by id
- PUT /product/{id} — Update a product resource by id
- DELETE /product/{id}- Delete a product resource by id
Database and Migrations
Let’s create our migration file. Run the following command:php artisan make:migration create_products_table
This will create a new migration file for you in the database/migrations
directory. Our product resource
will have the following attributes, name
, price
and description
.
Add the following code to the newly created migration file.
Edit .env
with your database
configurations and then run the following command to execute the migration. php artisan migrate
Creating our Product Model
You might already be used to creating models
and controllers
via artisan
commands in Laravel, but unfortunately Lumen doesn’t support those commands. To see a list of available artisan
commands in Lumen, run:php artisan
Navigate to the app
directory and create a new model
called Product.php
Unlike Laravel, Lumen does not initially load Eloquent and Facades. To be able to use them, we have to uncomment the following lines of code located in app\bootstrap.php
$app->withFacades();
$app->withEloquent();
Controller Methods
Let’s create our controller
. Navigate to the app\Http\Controller
directory and create a ProductController.php
file. Add the following code to the controller
you just created.
index
method returns all available products as aJSON
response.create
method creates a newproduct
and returns the newly createdproduct
as aJSON
response.show
method returns a single product resource by itsid
. This is also returned as aJSON
response.update
method updates a single product resource by itsid
as well.delete
method deletes a product resource by itsid
and returns asuccess
message.
Routes
It’s time to finally add our routes
. Open up the web.php
file in the routes
folder and add the following code:
We define group our routes
and add the prefix
api/v1
since it’s a common parameter shared by all our URIs
Tip: Make use of Prefix to specify common parameters for your grouped routes
Seeding our Database
Before we start testing our endpoints
, let’s create some sample data to work with. Let’s start by creating our seed
. Run:php artisan make:seed ProductsTableSeeder
This will create a ProductsTableSeeder.php
file in the database/seeds
directory. Edit the file with the following code:
Next, edit the DatabaseSeeder.php
file in the database\seeds
directory with the following code:
We’ll be making use of Laravel’s Model Factory and the Faker Library to generate the sample data. Navigate to the database\factories
directory and add the following code to the ModelFactory.php
file.
Next, run:php artisan db:seed
This will create a bunch of dummy data for us in our database
.
Testing our API
We’ll be making use of Postman to test our API. You can read more on getting started with Postman here.
Conclusion
In this tutorial, we’ve learnt how to build a simple REST
API with Lumen. Since the API isn’t production ready, there are a lot of improvements that can be made. You can find the repo on Github here and make contributions.