OpenAPI v3.1 Resources for Tooling DevelopersOpenAPI v3.1.0 has a bunch of great changes, solving problems like the subtle differences between JSON Schema objects and OpenAPI Schema…
Creating OpenAPI from HTTP TrafficAround this time of year we’re thinking about things we’re going to do differently, new practices we’ve been putting off for too long, and…
OpenAPI Examples Need HelpOpenAPI has come a long way since its nascent days as Swagger. It’s got excellent tooling, is talked about at all the conferences, is used…
API Evolution for REST/HTTP APIsThere are a lot of pros and cons to various approaches to API versioning, but that has been covered in depth before: API Versioning Has No…
Solving OpenAPI and JSON Schema DivergenceUpdate 2020-02-02: This article has been replaced entirely, as the proposed workaround was written into a now abandoned project Speccy, and…
OpenAPI and JSON Schema Divergence: Part 1This article is going to explain the divergence between OpenAPI and JSON Schema, which I’ve been calling the subset/superset/sideset problem…
Design-first API Specification Workflow MaturesBack in October I wrote Chasing the Perfect API Specification Workflow, which was a huge article about the state of the API specification…
Still Going on REST is the new SOAPOne month after A Response to REST is the new SOAP and I’m still having a productive dialog with the author, helping him understand how REST…
A Response to REST is the new SOAPEnough people have asked me about the article REST is the new SOAP that I felt it justifies a write up. Before I get started, I want to be…
One Month Since OpenAPI v3.0Last month today OpenAPI v3.0 was released, and not only is there a lot of cool stuff, but it unblocks some akward situations with vendor…
A Happy Compromise Between Customization and CacheabilityWith endpoint-based APIs (REST, RESTish, SOAP, RPC, AJAX-ish junk, etc.) you get to choose if you want increased likelihood of network cache…
Chasing the Perfect API Specification WorkflowDocumentation is a nice thing to have, but it is often treated as optional or superfluous, especially in teams where the clients and servers…
Representing State in REST and GraphQLRepresenting state is a complex thing. At my last two jobs, it’s been very common for APIs to be treated like “databases over HTTP”. The…
You Might Not Need GraphQLAfter writing about how GraphQL and REST differ in various regards, and taking a closer look at caching in particular, I wanted to write…
GraphQL vs REST: CachingRecently I wrote GraphQL vs REST: Overview, giving a hype-free outline of the differences between REST and GraphQL. One section that would…
GraphQL vs REST: OverviewA few months back I wrote a comparison between RPC and REST for Smashing Magazine, and now I want to talk about the differences between REST…
Building APIs with Rails: Documentation TestingNow that we’ve started building a very basic API, we should make sure that the documentation is kept up to date with our progress. Even…
Building REST APIs with Rails: Basic SerializationThird video in a pile of LiveCoding.tv videos, shows how to use ActiveModel Serializer to shape the output of your resources. I totally…
Mocking APIs with API BlueprintThe second video in a pile of LiveCoding.tv videos shows how to use your API Blueprint documentation to mock APIs, and a few different ways…
API Documentation: Do it FirstTwo years ago I finished the first edition of Build APIs You Won’t Hate, and since then I’ve worked on bigger and better projects, using my…
Dredd v1.1.0: A Bit DifferentA new version of Dredd - the API Documentation testing tool from Apiary Inc. - has been released, and it has changed a few things for the…
PUT vs PATCH vs JSON-PATCHA question that is asked with increasing regularity in the APIs You Won’t Hate Slack Group is one which has been asked for years, but does…
HTTP/REST API File UploadsFile uploads are one thing that always feel rather complicated, and working out how to handle this in an API doesn’t make life easier. For…
HTTP Documentation with API BlueprintWhen planning my talk and book on REST/HTTP API development, I ended up mentioning documentation towards the end, and flippantly said “Oh…
HTTP Status Codes Are Not EnoughI spotted an article called Just learn Rails (Part 3) HTTP status codes. It started off good, and I liked that it was teaching people to…
Auto-Incrementing IDs: Giving your Data AwaySomething we’re always taught as developers, usually by tutorials or via the defaults in various ORM tools, is every SQL table needs an auto…
Avoid Hardcoding HTTP Status CodesA lot of things in programming are argued to death, but one subject where people almost unanimously agree is that magic numbers can be a…
The Importance of Serializing API OutputI’ve given the API Pain Points talk a bazillion times over the last year. In just 2015 I gave it at: Lone Star PHP OpenWest ConFoo One…
Dredd: Do Your HTTP API JusticeUpdate 2021-02-08: Old post is old! I really don’t recommend messing with Dredd anymore, it was a handy stepping stone on the way to…
RESTful Deletions, Restorations and RevisionsTwo weeks ago I posted RESTful URLs: Actions Need Not Apply which was all about how the only action/verb to appear in the HTTP Request…
RESTful URLs: Actions Need Not ApplyI was doing a little consulting for a company while I was out in South Africa and we played the game. You fire SOAP functionality at me, and…
PHP API's: Fractal of GOOD DesignRecently I started a new blog series called “Build API’s That You Wont Hate”, starting off with Part 1 - Useful Database Seeding. It was…
Building a Decent APIUpdate: This initial list of tips is aimed mostly at beginners, but I expanded upon it so much I turned it into a whole book. I’m a little…