Build APIs You Won't Hate

Everyone and their dog wants an API, so you should probably learn how to build them.

Tasked with building an API for your company but don't have a clue where to start? Taken over an existing API and hate it? Built your own API and still hate it? This book is for you.

982 readers

100% Happiness guarantee Learn more

Minimum: $25.99

Suggested: $28.99+

Ways to buy

  • Free sample read /download
  • 982 readers
  • 135 pages
  • 31,860 words
  • 100% complete
  • Book language: English
  • Translations available: 3 translations
  • Updated

About the Book

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.

Buy A Bundle, And Save

  • Build APIs You Won't Hate cover page
    • Building Secure PHP Apps cover page

    Phil & Ben's Excellent adventures in Code => PHP APIs and Security Bundle

    2 books for $56.98 $34.99

  • Build APIs You Won't Hate cover page
    • Vagrant CookBook cover page

    Vagrant API's

    2 books for $51.98 $31.99

  • Build APIs You Won't Hate cover page
    • Laravel 4 Cookbook cover page

    The Laravel 4 Cookbook And Build APIs You Won't Hate Leanpub Bundle

    2 books for $58.98 $39.99

About the Author

I have seen a few trends come and go during my long and varied career of building stuff for money as an employee, freelancer, consultant and now CTO. One of the recent trends is the rise of APIs as an everyday part of the average server-side developers job.

A few years back when I was still an avid CodeIgniter user and contributor, I released a CodeIgniter Rest Server, wrote a few articles about how to use it and built out more APIs than I could shake a stick at for various clients. I knew at the time it wasn't everything that was required for an API, but it covered RESTful Routing, gave HTTP Basic/Digest/API Key authentication, added logging and throttling and did not force "PUT = CREATE OR DIE!" CRUD-based conventions and was leaps and bounds more simple than many of the options available for other frameworks. The internet agreed with me and this code is currently used by Apple, the UN and

Later on as a core-contributor to FuelPHP I added this functionality into FuelPHP, and again built out a bunch of APIs for people. Then I got offered a job in NYC and flew over to take over as head tech guy for a company that - you guessed it - had a FuelPHP API and wanted to improve it.

I've been building APIs for so long I have a very long list of ways to make them not suck. I'd like to share the information with you all.

About the Contributors

  • Alex Biblie Technical Review


    Alex knows his stuff about APIs. Previously working at the University of Lincoln he used to build out OAuth-based APIs for them. Then he moved to @VideoGamerCom and is doing the same for them, at a very high level. Alex also created the OAuth 2 PHP Server used in the later chapters, so is the perfect person to help out with technical review.

  • Ben Corlett Cameo Coder


    Ben helps out at Kapture now and then as a freelancer and took care of our original Behat testing. I gave him the vague plan for how I would like our Behat tests to run and he coded it up. He is responsible for the majority of the FeatureContext.php bundled in the Sample Code.

  • Mike Griffin Spellchecker


    Mike has been helping me sort out my awful typos and bad spelling like a champ.

The Leanpub Unconditional, No Risk, 100% Happiness Guarantee


Within 45 days of purchase you can get a 100% refund on any Leanpub purchase, in two clicks. We process the refunds manually, so they may take a few days to show up. See full terms.

If you buy a Leanpub book you get all the updates to the book for free! All books are available in PDF, EPUB (for iPad) and MOBI (for Kindle). There is no DRM. There is no risk, just guaranteed happiness or your money back.

Causes Supported


Electronic Frontier Foundation

Based in San Francisco, EFF is a donor-supported membership organization working to protect fundamental rights regardless of technology.

From the Internet to the iPod, technologies are transforming our society and empowering us as speakers, citizens, creators, and consumers. When our freedoms in the networked world come under attack, the Electronic Frontier Foundation (EFF) is the first line of defense. EFF broke new ground when it was founded in 1990—well before the Internet was on most people's radar—and continues to confront cutting-edge issues defending free speech, privacy, innovation, and consumer rights today. From the beginning, EFF has championed the public interest in every critical battle affecting digital rights.

10.0% of Phil Sturgeon's royalties are going directly to Electronic Frontier Foundation.

Other books by this author

Table of Contents

  • Introduction
  • Sample Code
  • 1 Useful Database Seeding
    • 1.1 Introduction
    • 1.2 Introduction to Database Seeding
    • 1.3 Building Seeders
    • 1.4 That’s about it
    • 1.5 Secondary Data
    • 1.6 When to run this?
  • 2 Planning and Creating Endpoints
    • 2.1 Functional Requirements
    • 2.2 Endpoint Theory
    • 2.3 Planning Endpoints
  • 3 Input and Output Theory
    • 3.1 Introduction
    • 3.2 Requests
    • 3.3 Responses
    • 3.4 Supporting Formats
    • 3.5 Content Structure
  • 4 Status Codes, Errors and Messages
    • 4.1 Introduction
    • 4.2 HTTP Status Codes
    • 4.3 Error Codes and Error Messages
    • 4.4 Error or Errors
    • 4.5 Common Pitfalls
  • 5 Endpoint Testing
    • 5.1 Introduction
    • 5.2 Concepts & Tools
    • 5.3 Setup
    • 5.4 Initialise
    • 5.5 Features
    • 5.6 Scenarios
    • 5.7 Prepping Behat
    • 5.8 Running Behat
  • 6 Outputting Data
    • 6.1 Introduction
    • 6.2 The Direct Approach
    • 6.3 Transformations with Fractal
    • 6.4 Hiding Schema Updates
    • 6.5 Outputting Errors
    • 6.6 Testing this Output
    • 6.7 Homework
  • 7 Data Relationships
    • 7.1 Introduction
    • 7.2 Sub-Resources
    • 7.3 Foreign Key Arrays
    • 7.4 Compound Documents (a.k.a Side-Loading)
    • 7.5 Embedded Documents (a.k.a Nesting)
  • 8 Debugging
    • 8.1 Introduction
    • 8.2 Command-line Debugging
    • 8.3 Browser Debugging
    • 8.4 Network Debugging
  • 9 Authentication
    • 9.1 Introduction
    • 9.2 When is Authentication Useful?
    • 9.3 Different Approaches to Authentication
    • 9.4 Implementing an OAuth 2.0 Server
    • 9.5 Where the OAuth 2.0 Server Lives
  • 10 Pagination
    • 10.1 Introduction
    • 10.2 Paginators
    • 10.3 Offsets and Cursors
  • 11 Documentation
    • 11.1 Introduction
    • 11.2 Types of Documentation
    • 11.3 Picking a Tool
    • 11.4 Setting up API Blueprint and Aglio
    • 11.5 Learning API Blueprint Syntax
    • 11.6 Further Reading
  • 12 HATEOAS
    • 12.1 Introduction
    • 12.2 Content Negotiation
    • 12.3 Hypermedia Controls
  • 13 API Versioning
    • 13.1 Introduction
    • 13.2 Different Approaches to API Versioning
    • 13.3 Ask Your Users

Last updated

This Book is for Sale Through Leanpub

Authors and publishers use Leanpub to publish amazing in-progress and completed books like this one.



Leanpub has a wide selection of in-progress and completed books available to browse, purchase, and enjoy.

Browse the Bookstore


Leanpub is free for authors and publishers to use. We pay authors or publishers 90% royalties minus 50 cents per sale.

Write a Book