Create Your First RESTful web service for Joomla! 3 with Lumen - Introduction

Category: Joomla
Create Your First RESTful web service for Joomla! 3 with Lumen - Introduction

Recently I decided to develop a simple blog application for iOS 9 with Swift 2. It’s pretty straightforward that the application needs to make a call to the website’s API and grab the output.

In my case I want it to be JSON and later in the application I’ll parse it and display the data either in the CollectionView or TableView. The blog runs on Joomla! 3. After searching for a while I discovered that there are no components for Joomla that would generate URL-s that would return JSON data.

So, needless to say, I had to do it on my own. After research I also discovered that you have to build web service from ground up or use any available framework to accomplish it.

The most popular PHP frameworks are Zend Framework, Symphony, Yii, Cake PHP and Laravel. There are several other micro frameworks designed to be used for building web services.

To make a choice you have to consider the “weight” of the framework, how fast it is, its simplicity, documentation, security and couple of other things.

Laravel has nearly made a revolution during past years. It’s been way more lightweight compared to Zend Framework and others, and its popularity brings more articles, better documentation and video tutorials. So if you are planning to dive in into PHP development, or move from any CMS to framework, Laravel is the right place to start.

In early 2015, Laravel released Lumen. Lumen is based on Laravel 5, though it contains libraries that are only required for building micro-services and APIs. In its own words “Lumen is the perfect solution for building Laravel based micro-services and blazing fast APIs. In fact, it's one of the fastest micro-frameworks available. It has never been easier to write stunningly fast services to support your Laravel applications”.

I decided to make use of Lumen and build RESTful API for Joomla! that I will later use for my iOS 9 application.

The tutorial will be divided into several parts. In the first part we will cover basics. In this introductory article we will install Lumen via Composer. Later we will define Models, Controllers, routes, add OAuth2 for limiting access to our API and then we will be handling errors.

So let’s get to it and develop RESTful API for Joomla! 3 with Lumen.

Installing Lumen is pretty simple as installing anything via Composer. If you don’t have Composer installed, you can read my article Installing Latest Version of Magento 2 1.0.0-Beta, where I cover Composer installation on a Mac and making it available globally.

The next steps are very simple. You can directly find Composer commands in the documentation of Lumen.

First, download the Lumen installer using Composer: composer global require "laravel/lumen-installer"

Installing Lument installer via Composer

Via composer create-project you may issue the Composer create-project command in your terminal:

composer create-project --prefer-dist laravel/lumen NAME_OF_YOUR_PROJECT

Before issuing the above mentioned command, you should navigate to the folder where you are planning to have your lumen project. In my case I navigated to my webserver root folder:

cd /Applications/XAMPP/htdocs

After running create-project command you will see that the required files have downloaded and we are ready to check if Lumen has been installed.

I placed my copy of Lumen in webservice folder so my URL is:

http://127.0.0.1/webservice/public.

Why public? We will cover Lumen’s folder structure in the next article, but for now let’s say that public directory, as the name states itself is the entry point of our webservice. In Laravel public directory is where your public assets are stored. Things like css, javascript and images are stored in this directory. But in case of Lumen you won’t be using assets, as far as we use Lumen for only web service purposes.

Open your browser and navigate to our webservice. You might see this page:

Lumen - Page you are looking for can't be found

Before we dive more into Lumen, just follow these steps:

Inside your Lumen installation directory, navigate to App -> Http -> routes.php. In the routes.php find this code:

$app->get('/', function () use ($app) {
    return $app->version();
});

Change the first parameter of the app->get() function call according to your installation path. In my case it looks like this:

$app->get('/webservice/public', function () use ($app) {
    return $app->version();
});

If you have installed Lumen prior to version 5.2.4, you will notice that the returned function welcome() is replaced by version(). So if you have installed 5.2.4 version, when you navigate to your Lumen address you will see message: Lumen (5.2.4) (Laravel Components 5.2.*).

Now let’s create our first route inside routes.php just to check if Lumen works. Add the following code:

$app->get('/webservice/public/hello', function () use ($app) {
    return "Welcome to the API";
});

If you didn’t understand what just happened, don’t worry! We’ll cover routes and many other things in the next article.

Now open your browser and navigate to http://127.0.0.1/webservice/public/hello and you will see Welcome to the API displayed.

For sure our URL looks ugly. If I was doing it on my hosting server, where are I have my blog, I would set a URL http://api.mrgott.com and point it directly to serverRoot/webservice/public. In that case we wouldn’t need to add /webservice/public into get() method call in the routes.php file.

In order to make to develop webservice in the more professional way, and at least make our localhost’s URL look better, I’ll write another article on how to set up virtual hosts on Mac OS X El Capitan using XAMPP. This will also be handy for Magento 2 tutorials that I’m planning to release.

Conclusion

I hope creating webservice with Lumen is as exciting for you as it is for me and I hope you will enjoy upcoming articles where will be setting up Models, Controllers and routes. We will cover one-to-many types in our Models and in the final article we will add OAuth2 for generating access tokens in order to secure our API. Cheers!