Annoyances of API Design

http://chickenwing.software/scratches/programming/annoying-apis

by ayi • 10 years ago

220 101 10 years ago

chickenwing.software

laveur2• 10 years ago

This is priceless! Pretty much contains everything that I hate about Android Development.

happywolf• 10 years ago

The title is misleading because this is focused on Android, but the title seems to imply generic API design pitfalls

yeukhon• 10 years ago

there's Apple. It is using Android as an example. I am pretty sure a lot of libraries do the same. To be more precise, the 6th is more likely for any GUI building toolkit out there. pretty much every single one of them end up a dozen of lines just to build a single thing.

gregmac• 10 years ago

The last half definitely devolves into Android API-bashing. The first half does generally apply to most APIs.

The main issue with most APIs boils down to documentation. Document it well, and it will largely be usable. This means everything from cross-references ("If you are trying to do X, ThisOtherMethod may be a better fit") to examples, and also extends to the API itself (good naming, and discoverable methods). Most developers using your API do not live in your API -- they live in their application domain. So you need to put effort into ensuring jargon is explained, the API is discoverable, and basically they can use the API easily, and get on with their application.

I really like the idea of thinking of API design in terms of Developer Experience (DX), in the same way that user interface designers consider User Experience (UX) about much, much more than simply the layout and colors.

ascagnel_• 10 years ago

Document it well, and it will largely be usable.

And a simple, easy-to-use API will also be comparatively simple to document. If you're at the point where writing documentation is hard, that's strong code smell that something is amiss.

erydo• 10 years ago

To be fair, Android has a hugely disproportionate number of API WTFs to choose from. It's an absolute mess.

Rockslide2• 10 years ago

The Objective-C example is not even close to the worst case :) I raise you

    shapeEffectSingleBlurFrom:withInteriorFill:offset:blurSize:innerGlowRed:innerGlowGreen:innerGlowBlue:innerGlowOpacity:innerShadowRed:innerShadowGreen:innerShadowBlue:innerShadowOpacity:outerGlowRed:outerGlowGreen:outerGlowBlue:outerGlowOpacity:outerShadowRed:outerShadowGreen:outerShadowBlue:outerShadowOpacity:hasInsideShadowBlur:hasOutsideShadowBlur:

(as queried with https://github.com/leoschweizer/Heliograph )

makecheck2• 10 years ago

I would guess that this method was created by a code generator, starting from a data structure with all of those fields.

More generally, a long initializer (or class method that returns an autoreleased object) is a fairly common pattern in Objective-C because it provides a common piece of code that all other initializers can call. There is usually some more obvious and convenient choice available, to avoid calling the horrible method directly.

bigblind• 10 years ago

Let's create the "Tweetable API" movement. If the most common call of a function doesn't fit in a tweet, you're probably doing it wrong.

JadeNB7• 10 years ago

If the most common call of a function doesn't fit in a tweet, you're probably doing it wrong.

As with all metrics, that can be gamed. Would

    s:o:b:iGR:iGG:iGB:iGO:iSR:iSG:iSB:iSO:oGR:oGG:oGB:oGO:oSR:oSG:oSB:oSO:I:O:

(the same arguments, obfuscated), which comes in at a much-reduced character count of 75, be any better?

Rockslide2• 10 years ago

In iOS 9, there currently seem to be 45 methods whose selector alone is longer than 140 characters. But how many of those are actually supposed to be used is another question ;)

pavlov• 10 years ago

Since nobody uses Obj-C without Xcode, you actually never need to type out a long method name. Typically you'd just write "sha", Xcode will autocomplete the method, and you press Tab to fill out all those parameters. Seeing them all at once as part of the method name is pretty convenient.

I'm not saying that the method name in your example makes any sense, it's definitely insanely long... But the Apple API mentioned in the original post is OK in my books because it's a rarely used initializer for a low-level object. It essentially wraps a raw C pointer into an object, so of course it needs all that metadata about what the pointer is! Putting the same data in a struct wouldn't save any typing.

dilap2• 10 years ago

hey now, I edit objc in emacs all the time!

wingerlang• 10 years ago

Sometimes I write it in Sublime. Although even then, I sometimes just write the method in Xcode to get the autocomplete then copy paste it, or just open the non-xcode-project file in xcode.

hohenheim• 10 years ago

I'm sorry but that sounds like a horrible excuse. Not only you are bound to a platform but also an IDE.

girvo• 10 years ago

Since nobody uses Obj-C without Xcode

Hey now, I do! But I'm convinced that I'm subconsciously some kind of masochist, so that's probably not proving you wrong.

cpeterso2• 10 years ago

Windows is known for having some rather long API names, such as RtlWriteDecodedUcsDataIntoSmartLBlobUcsWritingContext or EapHostPeerQueryUIBlobFromInteractiveUIInputFields. More examples at:

http://ashutoshmehra.net/blog/2010/02/long-function-names/

draw_down• 10 years ago

I think the selector in #2 is great. Sure it's long, so what. Reading it tells you exactly what the hell that line of code does.

beat• 10 years ago

There are only two hard problems in computer science - naming things, cache invalidation, and off by one errors.

Glad to see "naming things" made the top of the list. Names that are readable and sensible can be remarkably hard.

maxxxxx• 10 years ago

Writing a good consistent API for things of a certain complexity and maintaining and extending it for a long time is an extremely difficult thing. I have been doing this for a few years now and it's humbling to see how something that looked really smart a while ago is causing you major headaches now.

cballard2• 10 years ago

    outputImageProviderFromBufferWithPixelFormat:pixelsWide:pixelsHigh:baseAddress:bytesPerRow:releaseCallback:releaseContext:colorSpace:shouldColorMatch:

No, this is great! I can glance at something calling this, and, without any comments, determine immediately what each parameter is!

Note that standard formatting is to place each argument on its own line, with the colons lined up, and that Xcode does this automatically, and will autocomplete the entire nonsense. It's fairly disingenuous to line the whole thing up as if you need to type it all out.

Also, this is an API that clearly bridges to C-style data structures. Higher level APIs will have much fewer parameters.

What’s the difference between a tap and a touch?

In Apple-land, at least, a tap is an action (touching somewhere and releasing quickly, as opposed to a swipe, etc.), and a touch is where a user's finger is currently placed.

derrickdirge• 10 years ago

I couldn't agree more wrt the virtues of descriptive names. An enormous set of code comments is made redundant by the use of more descriptive names. Modern tools make it trivially easy to reproduce names of arbitrary length.

I can't see the downside, yet the author of the article acts like it should be obvious.

jt2190• 10 years ago

If I may offer the downside... :)

There exists a type of programmer who will write essentially the same lines of code over and over and over again. If you're this type of programmer, having to type long function names is extremely painful.

There exists another type of programmer who refuses to retype the same thing over and over, so instead uses some technique for reusing that code. If you're this type of programmer then long, descriptive names are preferable.

_yosefk• 10 years ago

Long names are hard to read. This makes autocompletion dangerous (I had a terrible bug where I locked the wrong of two mutexes with long, descriptive names which were too similar visually.)

A good name is short enough to read as a sign in itself, it shouldn't be parsed as a sentence.

The more code reuse there is, the less you might be using the same name, as a sister comment says - but the more names you have, and a lot of long names is really hard to read. So I disagree with sister's "downside" of "it's bad for bad programmers". It's even worse for otherwise good ones who buy into this style. (Or maybe not, maybe they just read differently from me and say Rob Pike who objected "names which are short essays about the thing they name.")

cbsmith• 10 years ago

Seriously, if you are annoyed by the long string, in most languages you can make a short form wrapper with trivial effort and trivial (if any) runtime overhead. I don't understand the complaining.

mikeash• 10 years ago

It's OK, but I wouldn't call it great. It's readable, but sort of hard to use. The trouble is that the interface is too flexible, more so than the underlying code, and so it's hard to know which combinations of parameters are legal. If you ask for a disallowed combination, you just get nil back and no explanation.

Edit: wrong API! This one does have a pixel format object.

It also tries to be helpful and so doesn't require all parameters. If you don't give it a data pointer, it will allocate memory for you. If you don't give it bytesPerRow, it will calculate it for you. These ought to be separate calls, not all glued together into one gigantic do-everything call.

The verbosity itself is fine, but it's symptomatic of some suboptimal API design behind it.

rbritton• 10 years ago

Though it's a C API, CGBitmapContextCreate is notorious for this.

While it doesn't address everything you're alluding to, I'm a big fan of Swift's nonnull/nullable making its way into Objective-C since some of Apple's APIs don't play well with a nil parameter (e.g., -[NSString isEqualToString:]).

dilap2• 10 years ago

Yup, I like it too.

Besides being clear w/o having to dig into references or source, it also makes 'oops, wrong variable order' bugs much less likely to occur (e.g., swapped width and height is obvious using the above, not so much if using positional args).

makecheck2• 10 years ago

Sometimes a long name is just a hint that the code wasn't factored enough.

For instance, the phrase "outputImageProviderFromBufferWith..." suggests that the Buffer concept should have been a separate thing (probably its own class), that OutputImageProvider could be constructed from.

danenania• 10 years ago

As with other types of interface design, the best way to write a good api is to get frequent feedback from the intended users.

Liberal application of the WTF test is critical[1].

As the author of the api, you yourself will be too close to it to judge fairly. Poorly named functions and over-complicated architecture will appear perfectly reasonable to you if you don't seek outside opinions.

1: http://commadot.com/wp-content/uploads/2009/02/wtf.png

aji• 10 years ago

'dup' is a bad example from C, in my opinion. ('dup' and 'dupe' are both short forms of 'duplicate' anyway.)

What about 'strncpy' versus 'strlcpy'? Or 'vsnprintf'? 'fcntl.h'? 'execlp'? 'EBADF'? 'SIGSEGV'? 'lstat'?

rossy• 10 years ago

Or 'tmpfile' and 'tmpnam'. Gotta save those characters. 'tempfile' and 'tempname' would be to hard to type. (Also, why not 'tmpfil'?)

to3m• 10 years ago

The number of significant characters in an extern symbol was only upgraded to 31 with C99... prior to that, it was all of 6.

kbutler• 10 years ago

creat

Gibbon1• 10 years ago

Course those come from a primordial age when max symbol sizes and file names were limited. Circa 1975 you were asking for trouble with a file name like string_copy.c or file_control.c

annnnd4• 10 years ago

Also, I kind of like the short versions. They are not any more difficult to remember ("Hmm, was it CopyFile of FileCopy?") and you need to search for them the first time around anyway. And it does save the effort when typing.

gaara87• 10 years ago

So... what is an example of a well written API/SDK?

brianwawok• 10 years ago

Stripe is decent.

JadeNB7• 10 years ago

So... what is an example of a well written API/SDK?

I think that this is an underrated question. I am not a programmer, but a mathematician; I will write from my experience in that field.

I was trying to understand a paper which used horrible, ad hoc notation that obscured the simple ideas at its centre. I invented a new, harmonious notation that beautifully revealed these simple ideas, and wrote a paper using it.

The notation was beatiful and harmonious as long as you were its inventor, and it was the most recent thing that you had been thinking about. Now, when I go back and read that paper … I think "wow, this horrible notation obscures the simple ideas at the centre of the paper."

Incidentally, I still think that the notation is better than the original; but the main thing that I've learned is to do it yourself before you complain about what someone else has done—after which (a) you'll have a good implementation and won't need to complain, or (b) you'll feel much humbler and won't want to complain.

allengeorge2• 10 years ago

Or maybe, the takeaway is: revisit your work later, when it's no longer fresh in your mind :) You'll understand what the strengths and weaknesses of your new design are, and are better placed to make an improved iteration.

Incidentally, writers have been doing this for years with drafts and editing. We definitely need to do that with our APIs and designs (aka. more incremental refactoring).

blakeyrat• 10 years ago

.net's standard library assemblies are generally excellent. A little verbose, perhaps. And very occassionnally a "what were they thinking?" moment (like WebClient throwing an exception for a 404 response-- fixed in HttpClient.) But overall, excellent.

int_handler2• 10 years ago

Agreed for the most part. My only gripe with the .NET world, and Microsoft's ecosystem in general, is the love for XML (#7 in the article).

m4yhem• 10 years ago

cpeterso2• 10 years ago

The Python "Requests" library is known for having a well-designed API, standing on the shoulders of API mistakes made by urllib[123]. :)

http://docs.python-requests.org/

dimonomid• 10 years ago

I enjoyed the read, entertaining and to the point, thanks.

Personally I'm in favour of long and descriptive names. I'm not afraid of typing. But since I'm writing in C (mostly embedded stuff), I'm not in the mainstream of the C community with my preferences. Sigh.

50CNT• 10 years ago

The "self-explanatory"/"brevity" problem is quite interesting. It reminds me of the point Donald Norman made in "The Design of Everyday Things", where information is either found in the world, or in our heads, coupled with issues of information-density. When we pick names, it's a trade-off between abbreviated (-> fast to use), descriptive (-> fast to learn), and mnemonic (-> easy to remember).

I roughly divide naming problems into 3 areas mentally. Most commonly used commands(/functions/identifiers/...), commonly used commands, and rarely used commands.

Most commonly used commands are things like ls or cd or mkdir. Due to their usage frequency, an intermediate user will remember these by heart, and mentally substitute their long forms whilst reading them out. Technically we could assign these to even shorter codes, but then they would loose their mnemonic value.

Preferably they would also have a long-form alias to provide a certain amount of easing into them. (list-directory, change-directory, make-directory)

Commonly used commands should not be abbreviated as readily. The few extra characters required to type them are usually well worth the additional clarity. Pythons .deepcopy() is a good example. It copies a data structure and its sub-structures completely. .dpcp() would be a lot harder to remember given how often it is used.

It should be possible to alias these to shorter versions as well, should someone have to use them frequently. Auto-complete functionality may also reduce the amount of memorization necessary whilst typing these in.

I personally think emacs handles these two cases very well, with it's quick chords that need to be memorized but provide speed, and calling commands by name via M-x which provides ease of use.

Then there's the rarely used stuff. These names may get very long if they are to be descriptive (ncursescplusplusmusicplayer), which means that they, or parts of them should probably be abbreviated (nccppmp, or preferably nccpp-musicplayer). Runs of abbreviated words should not become too long, 3-5 characters being the maximum. Past that length, it becomes hard to remember which characters one has already typed. (ncpmpp? or nccppmp?). Past that sensible chunking through full words or hyphenation may become necessary.

I do think these are sensible rules of thumb, but then they are rules of thumb, and there are most likely thousands of exceptions to them.

sundarurfriend• 10 years ago

Most commonly used commands are things like ls or cd or mkdir. [...]
Preferably they would also have a long-form alias to provide a certain amount of easing into them. (list-directory, change-directory, make-directory)

This reminds me of MS Powershell. `Set-Location` is the command for changing to a new directory location, and it's also abbreviated (aliased) as `cd`. Similarly with `ls` and many other commands. Powershell scripts often have the full forms of the commands, while in the shell itself you get the convenience of the shorter commands.

muzani• 10 years ago

Haha, this has a lot about what I hate about Android. I actually did quit programming and became a barista, because of the exact thing he said. Then I slowly got into programming again.

I actually started when Fragments were being introduced. Now that was a nightmare. The backwards compatibility was a red herring. The real problem was that Fragments were a poor practice, unsuited for many apps and teams... but Google played them out as The Next Big Thing. Today it's happening with Material Design.

annnnd4• 10 years ago

Not sure what you mean with the last sentence?

Anyway, Fragments are a nightmare. I learned them, I used them, and if I have to use them today I would still need to open that tutorial I have saved somewhere. That is one ugly solution if there ever was one.

njharman• 10 years ago

Annoyance the 5.1beta3 – Version incompatibility

That makes no sense. Yes, version X+1 is incompatible with version X. That's why we upped the version number!!!

I wonder if author never had to deal with API/Service that changed and was poorly or unversioned. Suddenly and mysteriously breaking things.

ktRolster• 10 years ago

It's annoying when an API isn't backwards compatible for no good reason. Android increases their version numbers quite often, which means you have to do extra work (which is annoying if someone is paying you, but worse if someone isn't).

Crockford said, "Changing an API is an act of violence." An API designer should think long and hard before breaking backwards compatibility: usually it's not necessary.

izacus• 10 years ago

Uh... Android's APIs are one of the most backwards compatible I've worked with (most applications written for 2.0 will work without issues on new Androids). Could you elaborate what extra work do you have to do? In comparison to what?

noselasd• 10 years ago

He's saying that APIs not providing backwards compatibility is annoying.

So yes, it's annoying when the next android release is out just as you're finishing your app, your code no longer works and you'll have to rewrite parts just because, while not receiving much benefit.

It's annoying as your application now likely have to support multiple versions of the API as well.

dpark3• 10 years ago

Version X.1 is not X+1. X.1 should contain no breaking changes. Otherwise your versioning is useless. If any change to the version number implies breaking changes, then you could replace the version with Rand() and it would do the same. If you're shipping versions like X.Y.Z for 3rd parties to consume, you should learn to use those minor and patch versions meaningfully.

hibikir• 10 years ago

Yes, XML is a big annoyance. But let me give you a bigger one: Json.

XML's saving grace was that it came with good schemas out of the box, so turning something from XML to, say, a Java object, was not very difficult. It wasn't difficult to use a SOAP service without having to do manual serialization work.

Today though, we are using something that has, at best, extremely weak types, and with schema equivalents that are bolted on, rarely used, and end up relying on humans understanding exactly what the data looks like, just for serialization/deserialization. I guess you can live with that easily if you are writing in a language that has really weak types in the first place, as you'd have to read the documentation anyway (What date format is the field using? Better go read about it), but the moment you try to do something even slightly more sturdy, the process is excruciatingly painful.

Heck, even tools like try to "help" document APIs, like swagger, end up with specifications that chill the bones.

It is as if the web was built for and by people that are absolutely allergic to both specification and types: In a more sensible world, we'd get something like: If the RDS is postgres, then the data format is like this, and if it's MySQL, it's like this instead. But what we have out there in the world is big lists of optional fields that will be illegal, or ignored, or who knows what.

I was a big XML hater, back in the days of SOAP, but the more I see how services are defined today, the better the old rust bucket looks.

rpd9803• 10 years ago

Haha, I've just always thought that if XML was too hard for you, maybe you should stick to graphic design...

sk5t• 10 years ago

I would argue that JSON wins by the maxim of "worse is better"; its vastly reduced feature set works to repel bad architects' efforts to incorporate horrendous and partially-supported WS-* concepts, external entities, doctypes, crazypants XSDs, and the horrors of XSLT--not that these things are bad in and of themselves, in fact they can be great, but interop can turn into absolute hell. IME if you have the luxury of working purely in .NET, on an updated, common version of WCF, and also nobody on the team goes wild with overdesign, the tooling and the things you can do are pretty great. OTOH testability is questionable, security might be bad, you spend a lot of time finding the right magic incantations to make everything work, and sometimes the tooling breaks in bizarre ways despite good efforts.

TLDR I used to be a big fan of XML, have switched to JSON, and probably won't be going back.

dpark3• 10 years ago

XML's saving grace was that it came with good schemas out of the box, so turning something from XML to, say, a Java object, was not very difficult.

Huh? How do you know what types <a><b c="d"><e/></b><b f="g" /><a> has? How do you transform that into a Java object? For that matter, if you manage to turn this into a Java object, how do you know how to transform it back into XML? What members turn into attributes and which turn into sub-elements?

Or are you referring to XSD, which showed up years later, is not required, and often not used? Yes, XSD grafts typing onto XML quite effectively, but this is a bolt-on just like the JSON approaches. It just turned out to be a widely-adopted bolt-on.

elktea• 10 years ago

Who cares what the XML looks like? You import the wsdl and off you go.

ubu7737• 10 years ago

XML's saving grace was that it came with good schemas out of the box

JSON is inherently "schema-less". So this provides us with no grievance.

something that has, at best, extremely weak types

You provide the reader with nothing that indicates that strong-typing is important for JSON use-cases.

schema equivalents that are bolted on, rarely used, and end up relying on humans understanding exactly what the data looks like

There are no schemas in JSON.

tbrownaw• 10 years ago

There is always a schema.

True, json has no formal explicit schema attached to the data.

However, there is still the ad-hoc informal schema that's defined by what the code interacting with the data does. Because this tends to be poorly specified and hard to get at, it's rather annoying to work with.

annnnd4• 10 years ago

I was a big XML hater, back in the days of SOAP, but the more I see how services are defined today, the better the old rust bucket looks

You really should try to use SOAP again, you will soon change your mind. I used it a few weeks ago (after about 5 years of peaceful life) and let me tell you - it still sucks.

The problem with SOAP is that, even if it is a standard, every $@%#*! library implements it in a slightly different way, leading to incompatibilities. Maybe it was just my luck, but every time I tried to use SOAP I ended up debugging XML envelopes and whatnot. With REST/HTTP + JSON? Just send, receive, parse, do what you want.

</rant>

daxfohl• 10 years ago

I have never needed a Kardashian for an API call.

TazeTSchnitzel• 10 years ago

Abbreviations can be annoying, but mainly because you don't know what they mean. I'd be less bothered by them if APIs using them would clearly document the meaning. Alas, that never happens.

euske• 10 years ago

API naming is hard because of the conflicting goals:

1. You want to make it easy to type/read. 2. You want to make it descriptive. (conflicting with #1) 3. You want to make it consistent and unique. 4. You want to make it compatible with older APIs. (conflicting with #3) 5. You want to make it unambiguous. 6. You want to make it flexible/amenable to future changes. (conflicting with #5) ...

etc, etc. It's just impossible to meet all these requirements with developers that live in a different time and space.

ericmcell2• 10 years ago

These are all library/SDK functions, can you just call anything an API nowadays? What application is my application interfacing with when I call an android SDK function?

ericmcell2• 10 years ago

Can you just call anything an API nowadays? These are all SDK/Library functions. What application is my Android app interfacing with when I call android SDK functions?

sgt2• 10 years ago

This is definitely an API; Application Programming Interface. An API can be a remote Web API such as a RESTful API or SOAP, or it can be against a shared library (i.e. a set of functions or methods) on your own computer.

LoSboccacc• 10 years ago

"What’s the difference between a tap and a touch? I have no idea"

TL;DR api design is hard because these are the programmers we write api for. Never happy, can't grasp the basic of the platform they're using, won't read any documentation to save their lives and expect all code to come to them magically perfect as if formed in a vacuum and not having a back-compat history.

frontsideair• 10 years ago

I'll just put this here: phpsadness.com

efaref• 10 years ago

why say dupe when we can save that valuable E and say dup?

"dup" is short for "duplicate", a saving of 6 characters, not "dupe", which means to deceive or fool.

spacecowboy_lon• 10 years ago

The main ones I find are

1 Using the wrong sort of approach for your api eg using a basic REST when the obvious paradime to use would be a Queue.

2 Documentation only comprehensible to insiders who all ready know the system backwards ( I am looking at you Google)

Jean-Philipe• 10 years ago

Thanks for speaking my mind! I especially enjoyed your word creations.

Annoyances of API Design

Related Stories