api

OpenAPI 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…

There 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…

Update 2020-02-02: This article has been replaced entirely, as the proposed workaround was written into a now abandoned project Speccy, and…

This article is going to explain the divergence between OpenAPI and JSON Schema, which I’ve been calling the subset/superset/sideset problem…

Back in October I wrote Chasing the Perfect API Specification Workflow, which was a huge article about the state of the API specification…

One 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…

Enough 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…

Last 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…

With endpoint-based APIs (REST, RESTish, SOAP, RPC, AJAX-ish junk, etc.) you get to choose if you want increased likelihood of network cache…

Documentation 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 is a complex thing. At my last two jobs, it’s been very common for APIs to be treated like “databases over HTTP”. The…

After writing about how GraphQL and REST differ in various regards, and taking a closer look at caching in particular, I wanted to write…

Recently I wrote GraphQL vs REST: Overview, giving a hype-free outline of the differences between REST and GraphQL. One section that would…

A 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…

Now 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…

Third video in a pile of LiveCoding.tv videos, shows how to use ActiveModel Serializer to shape the output of your resources. I totally…

The 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…

Two 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…

A new version of Dredd - the API Documentation testing tool from Apiary Inc. - has been released, and it has changed a few things for the…

A 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…

File 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…

When planning my talk and book on REST/HTTP API development, I ended up mentioning documentation towards the end, and flippantly said “Oh…

I 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…

Something we’re always taught as developers, usually by tutorials or via the defaults in various ORM tools, is every SQL table needs an auto…

A lot of things in programming are argued to death, but one subject where people almost unanimously agree is that magic numbers can be a…

Two 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…

I 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…

Recently I started a new blog series called “Build API’s That You Wont Hate”, starting off with Part 1 - Useful Database Seeding. It was…

Update: 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…