Build APIs You Won’t Hate

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’ll 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 it’s iPhone application to implement new functionality, so I used this as an opertunity to delete that mess and build v3 in Laravel 4, leveraging it’s 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 with this theory applied in examples built in PHP. I’m going to try and avoid making it code-heavy to stop you falling asleep and to keep the non-PHP developers happy.

Some of the more advanced topics covered here are endpoint testing, embedding data objects in a consistent and scalable maner, paginating responses (including embedded objects) and hypermedia controls (HATEOAS).

Please do not hesitate to get in touch if you have any suggestions or feedback.

Table of Contents

Chapter 1. Useful Database Seeding
Chapter 2. Planning and Creating Endpoints
Chapter 3. Input and Output Theory
Chapter 4. Status Codes, Errors and Messages
Chapter 5. Endpoint Testing
Chapter 6. Outputting Data
Chapter 7. Data Relationships
Chapter 8. Debugging
Chapter 9. Authentication
Chapter 10. Pagination
Chapter 11. Documentation
Chapter 12. HATEOAS
Chapter 13. API Versioning