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.

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.

Phil Sturgeon

Phil has spent years developing websites with a bunch of languages and frameworks such as PHP, Laravel, Ruby on Rails, Python and EmberJS to name but a few. Over the years he has ended up writing handfuls of APIs and worked implementing even more. This gave him considerable perspective on the good, the bad and the ugly of API development.

Being a core-contributor to CodeIgniter, FuelPHP and PyroCMS has given him some insight on framework-interoperability - leading him to join the PHP-FIG, which strives to make lives easier for developers through standards and interfaces.

Now he uses this extensive and random experience to try to improve the quality of code in the PHP community, one package, book, framework, or API at a time.

  • 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