Your API sucks : DDDScot follow-up

I was disappointed to miss DDD Scotland this this year, as I was looking forward to catching up with everyone and giving my talk. I’ll have to do the catching up another time, but if anyone wants me to give the talk, I’m available for conferences, user groups, weddings christenings…

There’s still a few discussion points I want to have around the talk, so I’m going to be posting some themes from the talk over the next few weeks to see what you think.

I wrote the talk as a catharsis for a project with 3 very bad APIs.  I don’t want to name them in the talk because none of them were the first time I’d seen the problem, and I’m trying to list general anti-patterns so that other developers can avoid the pitfalls. The key one being that for all the user experience research, most people still think of users and interfaces as graphical, not programmatic.

Before I start the rants though, I want to start with 2 thoughts about making an api that sucks less.


The best way to think of the user first, is to be the user first. That’s why I like Test-Driven Design. Write the API you want to use, then figure out all the horrible contortions behind the scenes to make it happen. That way you’re far less likely to introduce unexpected preconditions, because they’re harder to test. You’re far less likely to expose internal domain terms and models  so long as you’re not thinking about them yet. And you get to experience any frustrations first hand when you’re best placed to fix them.

Use BDD, use xUnit, use Postman, use the wonderful new .Net core


. Keep using them. Don’t accept any pain in your interface tests.

Rest, and be thankful

The talk unashamedly focuses on Web technology, and REST, for all the trial warfare, is a great way to think about the interface, and some of the basic lessons apply to other interfaces too:

  • Be open for extension – where you can, build extension points into the interface. Use dynamic models if you can, allow discoverable interaction (I’ve got my order, what can I _do_ with it?)
  • Use the standard – if you’re building on top of http, use headers, content-type, appropriate verbs, because existing clients and test frameworks support them, developers have learned how they work from other interfaces. Don’t be the stone in their shoe.
  • Minimise state transfer – don’t ask clients to remember, don’t ask clients to send or receive large amounts of data. Scope requests to the smallest sensible unit, and only ask for what you need.


Sometimes it will go wrong, and you will make developers cry. I’ll start talking about those next time but feel free to add your own below.

5 replies on “Your API sucks : DDDScot follow-up”

Good points. This should remind people of some critical items….yet it should also be pointed out that the concepts about simple/easy API’s are not new – see Effective C++ by Scott Meyers – published over twenty years ago!!!!!!

Given the long time that such information has been known, and the fact that it is still such an issue is something that should make many in the developer community stop and think….

Liked by 1 person

I agree. Obviously Web APIs are new, and I don’t think Web developers would think about picking up a C++ book, but these are the basics, and it’s frustrating that we need to keep revisiting them.


[…] 2016 was a big year for me. A new job, a new house and the first full year following the John Sonmez blogging course. I got back into public speaking, with my talk about APIs, and the follow-up usable APIs guided conversation at CodeCraftConf, although I missed out on the return of DDD Scotland. […]


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.