Build APIs You Won't Hate cover page
Build APIs You Won't Hate


Buy Now

Formats Included

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.

Build APIs You Won't Hate cover page Edit
This book is 100% Complete


Buy Now

Free sample

Read Download

Buy A Bundle And Save

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 opportunity 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 manner, 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

  • Introduction
  • Sample Code
  • 1. Useful Database Seeding
    • 1.1 Introduction
    • 1.2 Introduction to Database Seeding
    • 1.3 Building Seeders
    • 1.4 That is 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 Standards for Error Responses
    • 4.6 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)
    • 7.6 Summary
  • 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
    • 9.6 Understanding OAuth 2.0 Grant Types
  • 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
  • Conclusion
  • Further Reading

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 USA.gov.

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

  • 1130adb6ab1822ff8083a37b1641f79b

    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…

    Read more
  • 335320046b75045cc350157655fee8be

    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.

    Read more
  • 42185273_o

    Mike Griffin


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

    Read more

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.