API Best Practices

Fri, 14 Apr 2023 21:32:35 +0000

Creating great APIs is hard. Getting the right level of abstraction and building something that is pleasant for clients to integrate with is a huge challenge. This post delves into this topic in more detail.

But first an anecdote…
Product Owner: “I need you to integrate with this third-party API as part of the current feature. It provides most of the functionality that we require in this area, and will avoid us having to write loads of it ourselves. Here’s the link to their documentation.”

The Problem With APIs

Fri, 14 Apr 2023 20:32:35 +0000

Creating great APIs is hard. Getting the right level of abstraction and building something that is pleasant for clients to integrate with is a huge challenge. This two part post delves into this topic in more detail.

But first an anecdote… (courtesy of Russ Miles)
Provider: “Ah, you’re missing the special field, BABEL-256. Without that field this behaves subtly differently…”

Consumer: “Wait, what??”

Provider: “Yeah, you can think of this service as a single front door where, past the door, there are a lot of different rooms, hallways, and functions available. ‘Service DoSummat’ is just the front door. The concoction of fields you pass are where all the magic happens. It’s Postel’s Law, we accept almost anything and that’s a good thing…”

Design on Software Engineering Thoughts

API Best Practices

But first an anecdote…

The Problem With APIs

But first an anecdote… (courtesy of Russ Miles)