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 a JSON response.
• create method creates a new product and returns the newly created product as a JSON response.
• show method returns a single product resource by its id. This is also returned as a JSON response.
• update method updates a single product resource by its id as well.
• delete method deletes a product resource by its id and returns a success 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.

Testing with Postman

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.