Following on from Designing a RESTful API, this post will be a guide on building the API, itself.
The application will be used as benchmark for future posts, most of my decisions are simply because this setup is in my comfort zone.
The main tools I’ll be using are,
- Vagrant manages the virtual machine
- Scotchbox is a one-size-fits all LAMP stack image for Vagrant
- Laravel is a framework that is great at building RESTful APIs
- Composer is a package manager for PHP projects
Setting up the Virtual Machine
First we will clone Scotchbox Pro. Scotchbox Pro is a one-size-fits-all image which I like to use when I want to get straight into the code.
The non-pro does not have PHP 7.2, but alternatives are easy to find.
Run these commands to download the Vagrantfile from github,
git clone https://github.com/scotch-io/scotch-box-pro ctt-helloworld
cd ctt-helloworld
Then spin the virtual machine up (The first time you do this may take a while to download the image).
vagrant up
vagrant ssh
After calling vagrant ssh, you will be in the shell of the guest machine. The guest machine’s “/var/www” directory now points to the directory where “VagrantFile” is.
All commands will be run from inside the guest’s /var/www directory.
This is a good practice to ensure there are no host-machine dependencies; it also will be easier to explain things.
Setting up the project
Laravel will be the framework we are using. You could argue that Lumen would be more efficient fit for what we are building, but Laravel will offer more flexibility later.
This command will bootstrap a Laravel 5.5 (Current LTS) project in a “tmp” directory, then move the contents of that directory back into our home. (It will not install to an empty directory but my IDE has already added files…)
composer create-project --no-install --prefer-dist laravel/laravel:5.5.* tmp
cp -r /var/www/tmp/{.,} /var/www
rm -rf tmp
Extended Generators will generate migration scripts from the command-line.
composer require laracasts/generators --dev
Eloquent Model Generator will generate models a bit better than Extended Generators
composer require krlove/eloquent-model-generator --dev
Let Laravel know about the package providers (but only locally), update App\Providers\AppServiceProvider::register()…
public function register()
{
// Service providers only required by development
if ($this->app->environment() == 'local') {
$this->app->register('Laracasts\Generators\GeneratorsServiceProvider');
$this->app->register('Krlove\EloquentModelGenerator\Provider\GeneratorServiceProvider');
}
}
To finishing setting up the project, copy .env.example file, and update the database password to match the database provided by Scotchbox,
cp .env.example .env
sed -i -e 's/DB_USERNAME=homestead/DB_USERNAME=root/g' .env
sed -i -e 's/DB_PASSWORD=secret/DB_PASSWORD=root/g' .env
sed -i -e 's/DB_DATABASE=homestead/DB_DATABASE=music/g' .env
Setting up the database
Referencing the MVP data-structure from Designing a RESTful API, these commands build the migration scripts and models using Laracast’s generators…
albums, artist, and tracks are three simple meta tables for the time-being, “HasTimestamps” trait is generated, but not “SoftDeletes”, so I define the deleted_at manually.
php artisan make:migration:schema create_albums \
--schema="title:string, deleted_at:date:nullable"
php artisan make:migration:schema create_artists \
--schema="title:string, deleted_at:date:nullable"
php artisan make:migration:schema create_tracks \
--schema="title:string, deleted_at:date:nullable"
And finally a couple of pivot tables to define the relationships
php artisan make:migration:pivot tracks artists
php artisan make:migration:pivot albums track
The migration script will not create a schema for us, so let’s do that first
mysql -uroot -p -Bse "create schema music;"
Running the migration script will now create our database
php artisan migrate
Completing the models
Discard the models created by Laracast’s Generators, the package fall shorts on a few things that the Eloquent Model Generator solves.
rm -rf app/*.php
The Eloquent Model Generator to builds models based on the database structure itself.
php artisan krlove:generate:model Artist \
--namespace=App\\Models \
--output-path=Models
php artisan krlove:generate:model Album \
--namespace=App\\Models \
--output-path=Models
php artisan krlove:generate:model Track \
--namespace=App\\Models \
--output-path=Models
Logic and serialisation
Firstly create the resources, these will be used to shape our responses.
php artisan make:resource Album
php artisan make:resource Track
php artisan make:resource Artist
php artisan make:resource Albums --collection
php artisan make:resource Tracks --collection
php artisan make:resource Artists --collection
Creating resources controllers will save some effort when routing, but the controllers themselves will have a lot of dead code until we expand on the resources.
php artisan make:controller AlbumController --resource --model=Models\\Album
php artisan make:controller ArtistController --resource --model=Models\\Artist
php artisan make:controller TrackController --resource --model=Models\\Track
Update all controllers with this “index”, replacing the Resources and Album classes respectively.
public function index()
{
return new AlbumResources(AlbumModel::all());
}
The album controller needs two extra methods to handle the extra routes. Notice how “Album” into both methods, this is because of the static route binding we are about to do.
public function show(AlbumModel $album)
{
return new AlbumResource($album);
}
public function artists(Album $album) {
return new ArtistsResource($album->artists);
}
Read API Resources and Retrieving models in the Laravel Documentation for more information.
Setting up routing and controllers
Routing will serve to direct HTTP requests to the controllers which we created in the previous section.
Begin by defining some static bindings for the routes. This means we don’t need to handle whether the objects are available further down the line (It will handle 404s etc). Add the following lines to App\Providers\RouteServiceProvider::boot()
Route::model('album', 'App\Models\Album');
Route::model('artist', 'App\Models\Artist');
Route::model('track', 'App\Models\Track');
Define the routes in routes/web.php. Most routes can be handled with Route::resource(), but the specification defines additional ‘helper routes’, which logically map to other resources with an additional filter.
Route::group([ 'prefix' => 'v1' ], function () {
// Album resources (our vertical prototype)
Route::resource('albums', 'AlbumController')->only(['index', 'show']);
Route::resource('albums/{album}/tracks', 'AlbumController::tracks');
// Other resources
Route::resource('artists', 'ArtistController')->only(['index']);
Route::resource('tracks', 'TrackController')->only(['index']);
});
Read HTTP Routing in the Laravel Documentation for more information.
Populating the database with dummy data
At this stage, the RESTful API is almost ready, but we don’t have any data to respond with.
I eventually plan in populating the dataset with real-data, but for now I’d be happy with a dummy dataset.
To do this, I use a factory to create “fake” data, then seeder to populate the fake data into the database.
To bootstrap our factories, run the following commands
php artisan make:factory AlbumFactory --model=Models\\Album
php artisan make:factory ArtistFactory --model=Models\\Artist
php artisan make:factory TrackFactory --model=Models\\Track
Then we need to manually update each factory in database/factories to shape our data. “Faker” is used to randomly generate values. Our data doesn’t have much shape yet, so each factory should simple define a title…
$factory->define(App\Models\Track::class, function (Faker $faker) {
return [
'title' => $faker->name
];
});
Then go to database/seeds/DatabaseSeeder.php and replace the run method with a quick and dirty seeder. I attempt to create as many realistic ‘shapes’ of data as possible, whilst keeping it consise…
public function run()
{
DB::statement('SET FOREIGN_KEY_CHECKS=0;');
// Clear existing data
DB::table('artist_track')->truncate();
DB::table('album_track')->truncate();
\App\Models\Album::truncate();
\App\Models\Artist::truncate();
\App\Models\Track::truncate();
// Create 50 artists
$poolOfArtists = factory(\App\Models\Artist::class, 50)->create();
// Create 100 albums, each 10 tracks, each with 1 random artist
factory(\App\Models\Album::class, 100)->create()->each(static function(\App\Models\Album $album) use ($poolOfArtists) {
$tracks = factory(\App\Models\Track::class, 10)->create()->each(function(\App\Models\Track $track) use ($poolOfArtists) {
$track->artists()->attach($poolOfArtists->random());
});
$album->tracks()->attach($tracks);
});
// 50 tracks will be given a second artist
\App\Models\Track::all()->random(50)->each(function(\App\Models\Track $track) use ($poolOfArtists) {
$track->artists()->attach(
$poolOfArtists->whereNotIn( 'id', $track->artists()->pluck('id') )->random()
);
});
DB::statement('SET FOREIGN_KEY_CHECKS=1;');
}
To run the seeder, run this command:
php artisan seed:run
Read Database Testing in the Laravel Documentation for more information.
Querying the API
The app now respects the OpenAPI specification that we designed in the first post. Let’s call this the MVP.
Take a look for yourslef, here are some curl requests to try…
curl -X GET http://192.168.33.10/v1/artists
curl -X GET http://192.168.33.10/v1/tracks
curl -X GET http://192.168.33.10/v1/albums
curl -X GET http://192.168.33.10/v1/albums/1
curl -X GET http://192.168.33.10/v1/albums/1/tracks
And some 404s for good luck
curl -X GET http://192.168.33.10/v1/albums/999
curl -X GET http://192.168.33.10/v1/albums/999/artists
curl -X GET http://192.168.33.10/v1/albums/999/tracks
This post was a lot bigger than I expected it to be. In the next post in the series I’ll look at testing the application using the OpenAPI schema created in the previous post.
code to pen 