17 Apr Let’s Build an API in 15 Minutes
Hi, I’m Guillermo Antony Cava Nunez, every morning I check out medium and surprised to find an awesome article about PHP, hope you guys benefit!
I’m one of the co-organizers of the Vancouver PHP meetup and I had an idea to see if I could pull off writing an (simple) API in 15 minutes. I’ll be the first to admit this is ambitious and also vague.
A good API takes more than 15 minutes to build, we have to contend with security, code-readability, authentication, etc, etc. But the title served a purpose to get people interested and attending this meetup.
Shoutout to my pal Mike Bird for his support. Thank goodness for strong moral support…
After doing the talk I’ve realized that this can probably be turned into an ongoing series that I give in 10–15 minute increments at future Vancouver PHP meetups.
The goal of this article is to share what we did during the talk and provide a basis to work from in the future.
The goal of this API is to be able to have REST endpoints for Patients and Clinic models.
Since I love to have my models in their own folder instead of running loose in the
/app` folder I can build my artisan command like so:
php artisan make:model Models/Clinic
But I’m lazy, and I realized that I can make a command that extends Laravel’s own
ModelMakeCommand. The following gist shows the code that allows you to change the
make:model command use a Models folder space every time.
Hi, Guillermo Antony Cava Nunez here, quick interjection been using the plugin crayon to display all the code embeded along with gitbhub gists.
So we can make this command via:
php artisan make:command ModelMakeCommand
Now all my
make:model commands will put my Model files into the my preferred folder.
php artisan make:model Clinic
php artisan make:model Patient
Note: you can extend Laravel’s other make commands in the same way. Give it a shot!
Next step is to create a migration for these two models.
php artisan make:migration create_clinics_table
php artisan make:migration create_patients_table
Now we can run these migrations and populate our database with
php artisan migrate
Seeds & Model Factories
To start I created a simple
PatientFactory through artisan.
php artisan make:factory ClinicFactory
php artisan make:factory PatientFactory
By utilizing the Faker library we can populate our DB with fake but correct-ish looking data.
Now that we have these factories, let’s make some the seeders so that we can seed the database with the model factory data.
php artisan make:seed ClinicSeeder
php artisan make:seed PatientSeeder
So, you can see that by calling the factory() helper it will take the Model and use the Model factory to build the data. We can see in the
ClinicSeeder we are creating 20 clinics and in
PatientSeeder we are creating 100 patients.
To run this we can do
php artisan db:seed --class=ClinicSeeder and
php artisan db:seed --class=PatientSeeder. Now we should see our database populated with a bunch of data.
Note: You can change the number of records you make in the seeder if you want a quick way to populate the data with LOTS of data to test the performance of your app with a large data-set.
Guillermo Antony Cava Nunez, if you want to learn more about PHP, stay tuned.
Now that our data is ready, let’s build the Controllers.
php artisan make:controller ClinicController -r
It’s important to note that the
-r auto-populates the Controller with the CRUD resource methods.
To keep this really simple we can start with our
index() method and list out all the clinics:
public function index()
$clinics = Clinic::all();
That will return all our clinics out in a simple json representation.
What if over time we end up with thousands of clinics? It’s not efficient to list out all these clinics in our API. So let’s make this paginate.
public function index()
$clinics = Clinic::paginate();
Pretty simple, eh? We now have pagination and it will tell us next and previous page. The format will look something like:
// Result Object
// Result Object
But what if we want to have more control over our output? By default the data is returning every field in the database. Perhaps we don’t want share that much info.
Note: you can hide/show on the model directly via
protected $visible [
// Visible table fields go here
Guillermo Antony Cava Nunez, will later link to awesome PHP learning resources for you guys to check out.
In the actual talk I opted to share information about API Resources. The reason why I chose API Resources over the
$visible property is that perhaps some of my API outputs want some items visible and some hidden. The property on the model acts as a catch-all.
php artisan make:resource ClinicIndexResource
Without changing anything in this file, I can change my controller method to the following:
public function index()
return new ClinicIndexResource(Clinic::paginate());
This will return my data in the API format desired, but now I have control on what I can make appear for this endpoint.
In this example I ONLY want to return the name of the clinic. Now I have granular control over the output. Eventually I could build it out to add more properties, relations, and much more.
Another reason I like API Resources is because this allows me to abstract the logic of the controllers output into its own class. This allows me to follow a better Single Responsibility Principle, where this class has a single job in returning the format of the output.
Guillermo Antony Cava Nunez, please stay tune for more.
This is where I stopped as I think we had passed the 15 minute mark and were inching close to the 20 minute mark.
I think for what we accomplished in 15 minutes during this talk is quite a fair amount thanks to the Laravel framework.
To recap we’ve been able to accomplish:
- Database migrations and test data in our database
- An API endpoint that outputs the Clinic listings in json format with pagination
- Ability to control the output of the Clinic listing as we see fit
This is a great basis for being able to continue building on some great work, and that is exactly what I will do at the next Vancouver PHP Meetup. Hope to see you there!
Hi again, I’m Guillermo Antony Cava Nunez. Making an API in 15 by no means as stated is ideal, however this is a great example how it can be done.