TE
TechEcho
Home24h TopNewestBestAskShowJobs
GitHubTwitter
Home

TechEcho

A tech news platform built with Next.js, providing global tech news and discussions.

GitHubTwitter

Home

HomeNewestBestAskShowJobs

Resources

HackerNews APIOriginal HackerNewsNext.js

© 2025 TechEcho. All rights reserved.

Annoyances of API Design

220 pointsby ayiover 9 years ago

25 comments

cballardover 9 years ago
<p><pre><code> outputImageProviderFromBufferWithPixelFormat:pixelsWide:pixelsHigh:baseAddress:bytesPerRow:releaseCallback:releaseContext:colorSpace:shouldColorMatch: </code></pre> No, this is <i>great</i>! I can glance at something calling this, and, without any comments, determine immediately what each parameter is!<p>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&#x27;s fairly disingenuous to line the whole thing up as if you need to type it all out.<p>Also, this is an API that clearly bridges to C-style data structures. Higher level APIs will have much fewer parameters.<p>&gt; What’s the difference between a tap and a touch?<p>In Apple-land, at least, a <i>tap</i> is an action (touching somewhere and releasing quickly, as opposed to a swipe, etc.), and a <i>touch</i> is where a user&#x27;s finger is currently placed.
评论 #10991029 未加载
评论 #10992241 未加载
评论 #10993166 未加载
评论 #10991339 未加载
评论 #10999900 未加载
hibikirover 9 years ago
Yes, XML is a big annoyance. But let me give you a bigger one: Json.<p>XML&#x27;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&#x27;t difficult to use a SOAP service without having to do manual serialization work.<p>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&#x2F;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&#x27;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.<p>Heck, even tools like try to &quot;help&quot; document APIs, like swagger, end up with specifications that chill the bones.<p>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&#x27;d get something like: If the RDS is postgres, then the data format is like this, and if it&#x27;s MySQL, it&#x27;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.<p>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.
评论 #10993548 未加载
评论 #10994148 未加载
评论 #10993654 未加载
评论 #10993709 未加载
评论 #10993365 未加载
ajiover 9 years ago
&#x27;dup&#x27; is a bad example from C, in my opinion. (&#x27;dup&#x27; and &#x27;dupe&#x27; are both short forms of &#x27;duplicate&#x27; anyway.)<p>What about &#x27;strncpy&#x27; versus &#x27;strlcpy&#x27;? Or &#x27;vsnprintf&#x27;? &#x27;fcntl.h&#x27;? &#x27;execlp&#x27;? &#x27;EBADF&#x27;? &#x27;SIGSEGV&#x27;? &#x27;lstat&#x27;?
评论 #10992830 未加载
评论 #10992229 未加载
评论 #10992826 未加载
Rockslideover 9 years ago
The Objective-C example is not even close to the worst case :) I raise you<p><pre><code> shapeEffectSingleBlurFrom:withInteriorFill:offset:blurSize:innerGlowRed:innerGlowGreen:innerGlowBlue:innerGlowOpacity:innerShadowRed:innerShadowGreen:innerShadowBlue:innerShadowOpacity:outerGlowRed:outerGlowGreen:outerGlowBlue:outerGlowOpacity:outerShadowRed:outerShadowGreen:outerShadowBlue:outerShadowOpacity:hasInsideShadowBlur:hasOutsideShadowBlur: </code></pre> (as queried with <a href="https:&#x2F;&#x2F;github.com&#x2F;leoschweizer&#x2F;Heliograph" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;leoschweizer&#x2F;Heliograph</a> )
评论 #10990568 未加载
评论 #10989914 未加载
评论 #10989788 未加载
评论 #10992257 未加载
50CNTover 9 years ago
The &quot;self-explanatory&quot;&#x2F;&quot;brevity&quot; problem is quite interesting. It reminds me of the point Donald Norman made in &quot;The Design of Everyday Things&quot;, where information is either found in the world, or in our heads, coupled with issues of information-density. When we pick names, it&#x27;s a trade-off between abbreviated (-&gt; fast to use), descriptive (-&gt; fast to learn), and mnemonic (-&gt; easy to remember).<p>I roughly divide naming problems into 3 areas mentally. Most commonly used commands(&#x2F;functions&#x2F;identifiers&#x2F;...), commonly used commands, and rarely used commands.<p>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.<p>Preferably they would also have a long-form alias to provide a certain amount of easing into them. (list-directory, change-directory, make-directory)<p>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.<p>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.<p>I personally think emacs handles these two cases very well, with it&#x27;s quick chords that need to be memorized but provide speed, and calling commands by name via M-x which provides ease of use.<p>Then there&#x27;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.<p>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.
评论 #10994373 未加载
maxxxxxover 9 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&#x27;s humbling to see how something that looked really smart a while ago is causing you major headaches now.
euskeover 9 years ago
API naming is hard because of the conflicting goals:<p>1. You want to make it easy to type&#x2F;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&#x2F;amenable to future changes. (conflicting with #5) ...<p>etc, etc. It&#x27;s just impossible to meet all these requirements with developers that live in a different time and space.
happywolfover 9 years ago
The title is misleading because this is focused on Android, but the title seems to imply generic API design pitfalls
评论 #10989691 未加载
评论 #10990332 未加载
评论 #10989214 未加载
laveurover 9 years ago
This is priceless! Pretty much contains everything that I hate about Android Development.
dimonomidover 9 years ago
I enjoyed the read, entertaining and to the point, thanks.<p>Personally I&#x27;m in favour of long and descriptive names. I&#x27;m not afraid of typing. But since I&#x27;m writing in C (mostly embedded stuff), I&#x27;m not in the mainstream of the C community with my preferences. Sigh.
muzaniover 9 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.<p>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&#x27;s happening with Material Design.
评论 #10994176 未加载
gaara87over 9 years ago
So... what is an example of a well written API&#x2F;SDK?
评论 #10991051 未加载
评论 #10991285 未加载
评论 #10992223 未加载
评论 #10991032 未加载
评论 #10991968 未加载
spacecowboy_lonover 9 years ago
The main ones I find are<p>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.<p>2 Documentation only comprehensible to insiders who all ready know the system backwards ( I am looking at you Google)
danenaniaover 9 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.<p>Liberal application of the WTF test is critical[1].<p>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&#x27;t seek outside opinions.<p>1: <a href="http:&#x2F;&#x2F;commadot.com&#x2F;wp-content&#x2F;uploads&#x2F;2009&#x2F;02&#x2F;wtf.png" rel="nofollow">http:&#x2F;&#x2F;commadot.com&#x2F;wp-content&#x2F;uploads&#x2F;2009&#x2F;02&#x2F;wtf.png</a>
TazeTSchnitzelover 9 years ago
Abbreviations can be annoying, but mainly because you don&#x27;t know what they mean. I&#x27;d be less bothered by them if APIs using them would clearly document the meaning. Alas, that never happens.
efarefover 9 years ago
&gt; why say dupe when we can save that valuable E and say dup?<p>&quot;dup&quot; is short for &quot;duplicate&quot;, a saving of 6 characters, not &quot;dupe&quot;, which means to deceive or fool.
beatover 9 years ago
There are only two hard problems in computer science - naming things, cache invalidation, and off by one errors.<p>Glad to see &quot;naming things&quot; made the top of the list. Names that are readable and sensible can be remarkably hard.
frontsideairover 9 years ago
I&#x27;ll just put this here: phpsadness.com
LoSboccaccover 9 years ago
&quot;What’s the difference between a tap and a touch? I have no idea&quot;<p>TL;DR api design is hard because these are the programmers we write api for. Never happy, can&#x27;t grasp the basic of the platform they&#x27;re using, won&#x27;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.
njharmanover 9 years ago
&gt; Annoyance the 5.1beta3 – Version incompatibility<p>That makes no sense. Yes, version X+1 is incompatible with version X. That&#x27;s why we upped the version number!!!<p>I wonder if author never had to deal with API&#x2F;Service that changed and was poorly or unversioned. Suddenly and mysteriously breaking things.
评论 #10993670 未加载
评论 #10992579 未加载
评论 #10992545 未加载
Jean-Philipeover 9 years ago
Thanks for speaking my mind! I especially enjoyed your word creations.
daxfohlover 9 years ago
I have never needed a Kardashian for an API call.
ericmcellover 9 years ago
These are all library&#x2F;SDK functions, can you just call anything an API nowadays? What application is my application interfacing with when I call an android SDK function?
ericmcellover 9 years ago
Can you just call anything an API nowadays? These are all SDK&#x2F;Library functions. What application is my Android app interfacing with when I call android SDK functions?
评论 #10994814 未加载
draw_downover 9 years ago
I think the selector in #2 is great. Sure it&#x27;s long, so what. Reading it tells you exactly what the hell that line of code does.