Since 2010 I've worked as a freelancer, consultant, Head of API, and CTO, for several API-centric technology startups.
Previously at Ride, I was given the chance to work with amazing developers, including several Rails API contributors. We built an event-driven architecture with several REST APIs and a few RPC ones, and it was here I learned the benefits of REST being a state machine over HTTP.
Then at WeWork, I used my experience to help educate developers, define standards for API design and architecture, and work on open-source tooling for OpenAPI, JSON Schema, and HTTP. WeWork has 50+ APIs, and here I have had a chance to learn a lot about keeping distributed applications performant. Timeouts, retries, circuit breakers, keep alive settings, and HTTP caching specificially.
I try to turn all of this learning into books, videos, and articles, so others can learn easily things I've had to learn the hard way.
Articles by Phil
Commit to API Contracts
When building and maintaining a Web API, it's surprisingly common for the "I" (interface) part to be overlooked. Often new functionality is…
Caching is hard, draw me a picture
Another guest post from our friend Darrel Miller, this time explaining caching.
Creating API Specifications from Bulls**t
So you are using design-first for new APIs, but what about old APIs? Play catchup with a few sneaky methods.
Govern your APIs with Speccy
The last year has involved a lot of teaching engineers how to use OpenAPI, with the day job growing from a startup to a sizeable…
Picking the right API Paradigm
This article provides a decision flow diagram for selecting the “approach” to use for your next API.
Resolving Overloaded Terms for API Specifications… Descriptions… Contract?
Specifications, Descriptions, Documents, Spec Files, Contracts, ugh… they’re the same thing!
Why Do People Dislike JSON?
People seem to be moaning about JSON when they really just are upset with unspecified data.
API Evolution for REST/HTTP APIs
API Evolution is making a comeback these days, and REST advocates have been begging folks to use it for years. Let's learn how.
Common Hypermedia Patterns with JSON Hyper-Schema
But there are a few objectively terrible ways to handle it.
Getting started with JSON Hyper-Schema
JSON Hyper-Schema is a format for describing an API. You can automate a lot with a document that describes your API.
Getting started with JSON Hyper-Schema: Part 2
Let's learn a bit more about JSON HyperSchema, building on the foundation in part one, with resource representations, arbitrary request bodies, HTTP headers, and HTTP methods.
Let's Stop Building APIs Around a Network Hack
JSON:API has been one of the most popular standards for API development for a while now. It was conceived in 2013, battled through some...
Making the Most of JSON:API
If you absolutely positively have to use JSON:API for your API, here's how to make it not terrible.
OpenAPI and JSON Schema Divergence: Part 1
Update 20118–05–09: Hey hackernews, maybe read part two where we solved all the problems outlined here (one short term, one long term)…
Partials: Happy Compromise Between Customization and Cacheability
With endpoint-based APIs (REST, RESTish, SOAP, RPC, AJAX-ish junk, etc.) you get to choose if you want increased likelihood of network…
Representing State in REST and GraphQL
Learn how an API can become a state machine, with different actions appearing for resources in different states.
Solving OpenAPI and JSON Schema Divergence
My previous article explained the divergence between OpenAPI and JSON Schema (a.k.a the subset/superset/sideset problem), and promised…
Ruby Users: Be Wary of Net::HTTP
We discovered some fairly interesting behaviors in Net::HTTP recently, and figured we better share them.
Taking a Timeout from Poor Performance
In a system-oriented architecture, it is crucial to communicate with other systems, sometimes synchronously. Broker patterns, proxies, etc., or even just a remote procedure being triggered synchronously, like confirming an email has been sent successfully.
Testing API Client Applications
Got some code that talks to a Web API and want to make sure it works properly? Here's a bunch of options you can use to mock external dependencies.
Turning Contracts into Beautiful Documentation
Continuing on the topic of contracts — metadata that describes your data — it makes sense to see what easy early wins you can make from…
Surviving Deprecations to Resources and Properties on Other APIs
Deprecation, is the art of telling people to stop using that thing, because that thing is probably going away at some point. Even if there…
What is API Rate Limiting All About?
Learn what rate limiting is all about, and how you can train your HTTP client code to handle being limited.
Understanding RPC, REST and GraphQL
Every API is following some sort of paradigm, whether it knows it or not. Learn the differences, for when you talk to other APIs.
Writing Documentation via Contract Testing
Part of my day job is trying to get folks to write API documentation, so the hordes of new developers joining the company on a weekly basis…
GraphQL vs REST: Overview
An objective overview and comparison of REST and GraphQL, despite it being rather strange to try and compare a paradigm and an implementation.
Speeding Up APIs/Apps/Smart Toasters with HTTP Response Caching
Caching is a huge topic, and there’s a lot of different types of caching. No one type of cache is going to suite all needs and cover…
The Many Amazing Uses of JSON Schema: Client-side Validation
These days type systems are all the rage in APIs, so lets see how HTTP APIs can use JSON Schema for client-side validation.
Server-Side Validation with API Descriptions
Why waste a bunch of time duplicating validation rules in your application code and API description documents, then waste even more time trying to make sure these two disparate sources match up? Save a bunch of time and avoid mismatch bugs by using your API description as production code, so you have one source of truth, and your existing test suite can do the job of making sure things work.
REST and Hypermedia in 2019
A modern day look at the Richardson Maturity model, and insight into how the various layers of abstraction REST provides can help API Developers working in HTTP for various scenarios.
Creating Good API Errors in REST, GraphQL and gRPC
Dealing with the Happy Path™ in an API is pretty easy, but creating useful error messages can be tricky at first.
You Might Not Need GraphQL
Do you like the look of GraphQL, but have an existing REST/RPC API that you don’t want to ditch? Here's how to get those benefits without rewriting it.