Monday, January 9, 2017

Is there a perfect API Design?

Part I:The Problem


I write a verification framework called ApprovalTests. It uses itself to test itself and is generally bug free. So when exploratory tester extraordinaire Maaret Pyhäjärvi wanted to use it as a test target we were both rather excited. I was excited to show off how good automated testing and TDD can be. She was excited to show off how much it still failed to cover.

She won.

To be clear, the stuff I tested was pretty solid. However, I was woefully incomplete on the system as a whole. A mere hour of testing discovered gaping holes in different environments, documentation and onboarding of new users, and usability issues with my API.

These are hard problems, many of them still haven't been solved and I wanted to talk about one in particular that I am still struggling with today:

Naming


I use something called reporters and annotations in ApprovalTests. It means you can write code like

[UseReporter(typeof(DiffReporter))]

The issue was in discoverability. If you start typing this you get very little help from your editor:

You get some other reporters [KDiff, Tortoise] but not many and these happen to be useless and DiffReporter will use them if they exist on your system anyways.

If you typed "Reporter" instead this goes away and the over 50 options will present themselves to you, but it's not intuitive to this and a few painful usability tests showed this to me over and over as I watch is silence and frustration.



Renaming can fix this

[OnFailure(typeof(ReportWithDiffTool))]

I ran an online poll, most people preferred this. 70% vs the 30% that preferred the previous version.
I think I'm in the 30%, I prefer my classes to have Noun names, but I might be partial because this is what I'm used to.

So I'm faced with changing a lot of the API.

The issue is:


How do I know which one is the right answer?

How do I know there *is* a right answer?


Part II: 2 Pepsis and the world of choice

Malcolm Gladwell did a great Ted Talk on choice. In it he talks about a taste test to find the perfect sweetness for Pepsi. There were 2 peaks, so they averaged them out, but this isn't the right answer, the right answer is there are 2 preferences for sweetness. Because of this as a culture we have changed from a single 'perfect' spaghetti sauce to an aisle of choices


Maybe we should have the same occur with API's?
Maybe the issue isn't to have either UseReporter or OnFailure. Maybe I need to have both.

This requires a bit of finesse. I don't yet have answers on how to version and package these solutions.
Should they be in separate nuget packages? Should they interplay with each other?
How to I balance having a clear way with choice paralysis.

I don't know the answers to these questions, but I am beginning to see that maybe there isn't the one perfect API...

5 comments:

Frans Lytzen said...

The thing about choice... Too much choice reduces consumer happiness. And I think that is even more true here. If you have two names for the same thing you will inevitably increase cognitive load and have conflicting blog posts and documentation out there.
Just imagine being a new user and having to decide which of the manic approaches you like; getting your head around Reporters is plenty hard enough :)
So, choose one approach and stick to it IMO :)

Llewellyn Falco said...

yeah, that the balance that has to be achieved. still I don't think the answer is 1. And there needs to be a way to improve and let go of mistakes of the past.

Bpk radi said...

Buat saudara punya permasalahan ekonomi: hub aki santoro,karna saya sudah membuktikan bantuan aki santoro yang berminat,hub aki santoro di nomor 0823 1294 9955, atau KLIK DI SINI

Bpk radi said...

Buat saudara punya permasalahan ekonomi: hub aki santoro,karna saya sudah membuktikan bantuan aki santoro yang berminat,hub aki santoro di nomor 0823 1294 9955, atau KLIK DI SINI

pak irwan di jayapura said...

Jika anda butuh bantuan nomor togel atau dana gaib dijamin sukses nama saya pak irwan murid MBAH BUDI HARTONO saya sendiri sudah membuktikan angka 4d nya SGP syukur alhamdulillah dapat kemenangan 570.juta saya sudah bisa bayar hutang dan sudah bisa buka usaha bagi anda yang punya permasalahan ekonomi atau terlilit hutang sudah lama belum lunas jangan putus asa lansung hubungi MBAH BUDI HARTONO di no 085-256-077-899 atau buka website MBAH silahkan KLIK DISINI NOMOR TOGEL DAN DANA GAIB