Build APIs You Won't Hate: Everyone and their dog wants an API, so you should probably learn how to build them (2014)


I’ve been building APIs for a long time now and it is becoming ever more common for server-side developer thanks to the rise of front-end JavaScript frameworks, iPhone applications and API-centric architectures. On one hand you’re just grabbing stuff from a data source and shoving it out as JSON, but surviving changes in business logic, database schema updates, new features or deprecated endpoints, etc gets super difficult.

I found most resources out there to be horribly lacking or specifically aimed at one single framework. Many tutorials and books use apples and pears examples which are not concrete enough, or talk like listing /users and /users/1 are the only endpoints you will ever need. I’ve spent the last year working at a company called Kapture where my primary function has been to inherit, rebuild, maintain and further develop a fairly large API with many different endpoints exposing a lot of different use-cases.

The API in question was v2 when I joined the company and written in FuelPHP, utilizing a now deprecated ORM which had been hacked to death by the original developer. Kapture was in the process of rebuilding its iPhone application to implement new functionality, so I used this as an opportunity to delete that mess and build v3 in Laravel 4, leveraging its simple (initially Symfony-based) Routing, Database Migrations, Schema, Seeding, etc. Now we are doing the same for v4 but no rewrite was required this time, even though we have some different functionality the v3 repo was forked to a new one for v4 and both are being actively developed and living side-by-side on the same “API” servers.

By passing on some best practices and general good advice you can hit the ground running if you are new to API development. On the flip side, by recounting some horror stories (and how they were overcome/avoided/averted) you can hopefully avoid a lot of the pitfalls I either fell into, or nearly fell into, or saw others fall into. This book will discuss the theory of designing and building APIs in any language or framework. This theory will be applied in examples built mostly in PHP, with some Ruby and Python too. The book will not be too code-heavy regardless, as reading code is no fun.

By the end of this book, you will have built an API that can handle create, read, update, delete, listing, searching and everything else a good RESTful API needs to do. Some of the more advanced topics covered here are endpoint testing, debugging, embedding/nesting data objects in a consistent and scalable manner, paginating responses (including embedded objects) and HATEOAS links.

Sample Code

Throughout this book I will refer to source code which exists on a GitHub repo, which can be downloaded in a few ways.

a) You can clone it:

1 $ git clone

b) Browse around it:

c) Download it as a .zip file:

This contains a few bits and bobs that will save you from copying and pasting things out of the ebook, which would probably be horrendous.

The book will assume you place the contents in ~/apisyouwonthate, so if you put it somewhere else update the path in the examples.