[HN Gopher] The unbearable frustration of figuring out APIs
___________________________________________________________________
The unbearable frustration of figuring out APIs
Author : ezekg
Score : 62 points
Date : 2026-01-14 16:28 UTC (6 hours ago)
(HTM) web link (blog.ar-ms.me)
(TXT) w3m dump (blog.ar-ms.me)
| alexjray wrote:
| Show me the incentive and I can likely guess how hard your API is
| to use.
| Svoka wrote:
| This is strangest read I had in a while. It is like saying that
| operating a submarine is very counter intuitive, I know how to
| operate an airliner, both are vehicles.
| stevedonovan wrote:
| It was my first taste of Swift, and has destroyed any lingering
| curiosity I had about it.
| bfbf wrote:
| As a Swift dev, I have to say this was a frustrating read.
|
| Apple's documentation is often very poor, and I will note
| that Swift Packages (especially CLIs) doesn't always feel
| great. As another commenter noted, anything other than Xcode
| feels like fighting an uphill battle.
|
| But many of your frustrations could be solved by checking not
| API docs, but just the Swift language guide. You seem
| perturbed, for example, that the Package initializer expects
| ordered arguments. It is a basic part of Swift's design that
| arguments are always ordered and exclusively are either named
| or unnamed (never optionally both).
|
| The ghost's use of semaphores with async/await is a massive
| red flag in terms of mixing two asynchronous frameworks
| (Concurrency and GCD). I'd not be surprised if it worked, but
| that's really against the grain in terms of how either
| framework were designed. This is the shortfall of relying on
| bottled ghosts to learn new tools. I know from experience
| that the documentation on Concurrency (async/await) is pretty
| good, and lays out a clear rationale for how it's intended to
| be used, but that is a huge piece of documentation and it's a
| big hill to climb when all you're building is a small tool.
| This is the risk we run when asking AI for help when it
| itself is ignorant of the actual intended use of the apis and
| is only trained on the output of developers. Here it's easy
| to see that it was faced with a problem of synchronous access
| to an async function and reached for a common solution
| (semaphore), despite the fact that semaphores are part of a
| 10 year old framework, and the async/await keywords are only
| 2-3 years old!
|
| Anyway, the article reminded me of the challenges of learning
| a new (programming) language. There's more to it than just
| following tutorials and blindly directing AI. I know the
| feeling, having to currently learn c# at the moment. I can
| write simple functions and follow the syntax, but I can't
| intuitively understand what's happening like I can with
| Swift. Is that because Swift is better than C#? Not really-
| it's just that I'm fluent in one but not the other.
| Ironically I guess you probably get this already from
| learning Mandarin, but you've not written an article about
| how frustrating it is that it inexplicably insists on using
| tones to express meaning, when English is fine without it(!).
|
| I'm sorry you had a bad experience with Swift. I do genuinely
| think it's a great language to write, and the open source
| Swift Evolution team are great. They are continually pushing
| for more openness and more cross platform compatibility, and
| I do like the way that the core of the language is strongly
| opinionated in a way that makes it clear what's happening if
| you do understand the syntax. What's hard is then the
| application of Apple's APIs which are wildly inconsistent and
| often incomplete. Some are maintained while others are still
| wrappers for 15 year old objective C that have no concept of
| modern Swift paradigms. That said, I'd still encourage you to
| persevere with Swift. Once you get past those rough edges of
| stdio and UI and get into the heart of a Package, I would
| expect most of these complaints to disappear!
| TeMPOraL wrote:
| More like, operating a submarine that's being designed and
| built-up around you as you travel in it, with half the
| components being obscure military secrets that - for reasons
| unknown - don't come with operator manuals anymore, and the
| other half being done by children copying designs they saw in
| TV shows with duct-tape and plasticine.
|
| That's how modern software industry feels like.
| blumenkraft wrote:
| In all honesty this is how a typical developer experience has
| been for a long time in a number of systems. Expecting someone to
| pre-chew your programming food is silly.
| Bratmon wrote:
| The difference is that most of those systems have documentation
| that explains how to use their weird APIs.
| a1o wrote:
| > You probably already know this, but apparently the first line
| in the file, that comment, is actually significant.
|
| I did not knew this.
| dvh wrote:
| For me the worst APIs by far are on Android. They are even worse
| than win32.
| behnamoh wrote:
| Nope, Google AI APIs are second to none. That shit will make
| you question whether their services are worth it.
|
| Edit: Come to think of it, both are made by Google :')
| taeric wrote:
| Agreed. Amusingly, a lot of what makes them worse than some
| older alternatives is that they "fix" things constantly by
| reworking how to use them. Older paths may be bad, but effort
| has been made into getting them to work.
| m-schuetz wrote:
| Can anything be worse than Vulkan?
| manithree wrote:
| Ever used the self-hosted BitBucket (formerly Stash) API?
| lacoolj wrote:
| I'm really sorry, but when someone posts an entire article that
| they don't first proof-read at least once, it makes me question
| the rest of what I'm reading and can't continue.
|
| > ... I found mysekf launching TextEdit just to do that
|
| I hope everyone else enjoys it!
| saulpw wrote:
| on the one hand, why didn't they just pump it through the
| "Ghost" and have it fix all the problems for them?
|
| on the other hand, I appreciated knowing that it was actually
| written by a frustrated human, and not sanitized by the Ghost.
| TeMPOraL wrote:
| That's the thing: if you ask the Ghost to write as if a
| frustrated human, it'll happily do so.
|
| LLMs are good at style transfer _in fully general sense_ ,
| they can introduce typos and bad grammar just as easily as it
| can correct them.
| saulpw wrote:
| That's fine, and I know that, but I have never heard of
| anyone doing that to publish something 'more human' on
| their blog. Not to say that it's never happened, but when I
| see some pretty basic typos in a blog post that also sounds
| like actual human frustration, Occam's Razor says it's fair
| to assume that a human made those typos.
| TeMPOraL wrote:
| I've seen non-tech people doing that both by hand and
| automatically, specifically to make the e-mails and
| documents look human-authored. I'm convinced this is a
| very common behavior.
| otikik wrote:
| I like it. It tells me this wasn't written by AI
| marcellus23 wrote:
| All of this is written with a sense of anger and sarcastic
| invective that doesn't seem appropriate. This is part of learning
| any new language or API. Going in with an attitude of "I should
| already know how all this works, why am I forced to do research
| or look at docs?" seems unfair and will spoil the experience of
| learning anything.
|
| > Why was that so hard? Why are the models here separate from the
| ones in the right click menu? Too many questions.
|
| The very screenshot above this paragraph actually answers this,
| in what admittedly might be an uncharacteristically clear UI:
| "Siri and Safari will always run translations online."
| n8cpdx wrote:
| This is a story about the risks of AI-induced brainrot. You get
| so used to having the computer just do your work, that the
| second you need to engage your noggin you're lost at sea. Or at
| least just frustrated.
|
| Reading and understanding the docs and reference material has
| always been part of the work.
|
| Aside from the commentary it read like an advertisement for how
| great the swift/macos translation APIs are. PEBCAK
| IncreasePosts wrote:
| The problem is there are a wide class of problems that you
| want solved but putting on the work will prevent you from
| actually doing the task because the cost isn't worth the
| reward. Because it's for a low impact tool. Or you can't
| imagine yourself dealing with this API again within a year or
| two by which time it will probably be completely different
| with v2 of the API.
|
| So, you reach for AI and it works really well. So you start
| reaching for that more and more...
| adventured wrote:
| Having no minimum wage for LLMs is fantastic. It opens up
| all manner of work that had previously been priced out.
| thorum wrote:
| I remember reading and hearing similar rants from programmers
| 15 years ago, long before LLMs. The author kept going and
| figured it out, and probably got some pride and enjoyment
| from finishing the project in spite of the frustrating
| moments. That's what learning to code has always been like.
| bfbf wrote:
| Gotta say as a Swift dev I agree--followed the link the to
| Translate docs and was pleasantly surprised to see a
| discussion section clearly explaining the usage, which is not
| always the case for Apple APIs! But this wasn't really just
| an article about the API. It was about the complexity of
| trying to build on the stack of
| Swift/SPM/ParseableCommand/Foundation/Concurrency/Translation
| without having a good grasp of any of them. I was frustrated
| reading it, but I think it does point to the underlying
| knowledge that's needed to be proficient at something like
| this. None of it is a particular indictment of Swift as an
| ecosystem (though there are lots of valid criticisms)-it's
| just the nature of development and something that's massively
| eroded by relying too much on these ghosts
| brabel wrote:
| Most of the author's frustration was due to lack of good
| feedback from Swift.
|
| Like, how can it run a command that has an `async` main despite
| the fact that you didn't extend the async version of command??
| That should've been an error (e.g. "bro, you cannot have an
| async main in this class, you need the Async version of this
| class which is called AsyncWhatever").
|
| Not awaiting on an async function should be at least a warning.
| Another frustrating lack of feedback: it just lets you run it
| and nothing happens.
|
| The version thing: it should show all possible variants in the
| enum, even the ones you should not be able to use, and then
| when you try using it, show an error saying "you need to change
| the version of this file to at least blah to use this". Why
| can't the Swift LSP do that? Apple has a trillion dollars, they
| can afford polishing their stuff.
|
| The author is used to Rust, which would've made it very clear
| what was wrong in all cases.
|
| Swift, being as modern as Rust, should be doing better than
| that. Languages that fail to give you proper error messages and
| warnings are just not worth it: just one of these "wtf is going
| on?" moments can cost you hours. Just use a better language if
| you can.
| eptcyka wrote:
| Swift ultimately is a language that is expected to be
| compiled by xcode. Package.swift isn't even properly
| supported by Xcode still.
| eptcyka wrote:
| Coming from other languages, figuring out how to get an
| NWConnection to work was not trivial and just reading the
| interface docs did not help. I empathise with the frustration
| of reading apple docs. Sure, the tone isn't professional, but I
| don't believe that is out of place.
| another_twist wrote:
| Disagree here. APIs are meant for using and not learning. But
| the context matters here. For some paid system, there better be
| an API thats easy to use or I am throwing AI at the problem or
| hoping someone else will do it. If its something worth learning
| - say Guava data structures or RocksDb core - yup I'll invest
| the time to learn. That learning transfers over. But trying to
| learn some shitty AWS api and its nuances, no thanks. Some
| payment system that a handful of people use - no thanks again.
| epgui wrote:
| Language is meant for using, not learning. Why is
| Arabic/French/Chinese/etc so difficult?
| Johnny_Bonk wrote:
| One thing you could consider doing, is using Claude in chrome
| extension and having it help you read through the api docs with
| you and gather sort of cheatsheet, it's helped me immensely, it
| can click through and parse pages etc.
| akhil08agrawal wrote:
| The "finally got it working then realized Spotlight already does
| this" moment is brutal.
|
| API design isn't just about functionality. it is about
| discoverability and if your right-click menu uses different
| models than your API and your error messages don't explain why,
| you are just creating friction for no reason.
|
| Sometimes the "proper" solution isn't worth the super complicated
| maze.
| Shuddown wrote:
| I must be missing something here. Why would anyone want to use
| Apple's god awful translation models? Is it perhaps better at
| translating individual words? Anytime I've used it for article
| translation it has been unequivocally terrible.
| frizlab wrote:
| Did you use it recently? I used it to translate a Chinese
| website to English and was surprised to see everything made
| sense. Even the texts on the images were translated (in
| Safari).
| nabbed wrote:
| Way, way back in 2003 or thereabouts, I had to add an "open this
| report in Excel" function to an existing product. But first I had
| to figure out how to convert the report to Excel format (with
| freeze panes, etc.). I found Apache POI and was very happy with
| its API documentation, especially this "Busy Developers' Guide to
| Features": https://poi.apache.org/components/spreadsheet/quick-
| guide.ht...
|
| This page was much simpler 22 years ago (I don't remember this
| HSSF stuff, whatever that is), but it still looks familiar.
| Basically everything I needed to do had examples in there. I
| remember thinking that the authors cared about the users of the
| library (although the Javadoc seems a little bare.. but I am not
| sure I needed the Javadoc much).
|
| If I ever create an OSS library, I would certainly also create a
| "Busy Developers' Guide".
| another_twist wrote:
| Every library I have ever considered using and almost all of
| the ones that I onboarded have a "Quickstart" section. eg
| Guava, Guice,
| Salgat wrote:
| My biggest frustration with docs is when they don't provide
| examples. Seems like whenever examples are included, everything
| becomes much easier to understand because you have an explicit
| usage to reference.
|
| I've always loved Microsoft's API Browser for this reason:
| https://learn.microsoft.com/en-us/dotnet/api/system.net.netw...
| ks2048 wrote:
| Not mentioned in the blog post, but he links to an Apple API
| documentation page, which itself links to a full sample app
| using Translation API,
|
| https://developer.apple.com/documentation/translation/transl...
| joshstrange wrote:
| To be fair, Apple is known for having bad docs (for at least
| the past 5-10 years) that often don't have examples or sample
| code, I think that's more of an outlier.
|
| I don't regularly develop in swift, but when I have, I've
| been confused by the docs because they are so clearly auto
| generated (not LLM, just from the code) and sparse. Listing
| out constants is next to useless when they are confusingly
| named and have no description of what they mean or how the
| affect things.
| classicsc wrote:
| If you want the ghosts to hallucinate less on things like this
| you should hook them up with the sosumi MCP. It's been very
| helpful to me since it seems like Apple's newer APIs are not in
| the training set of today's models.
|
| When working on my own projects I've found a good rule of thumb
| to be that if you are being told to use something low level and
| unintuitive like a semaphore in Swift when doing something that
| ought to be easy, you are probably either reading a stackoverflow
| answer from an objective-c developer or in the middle of a LLM
| session that's gone sideways. Low level libraries might need
| those things, they are approximately never right for application
| code. Just throw it out and start over (as you did), saves on
| sanity.
| mwkaufma wrote:
| "The Unbearable Frustration of Figuring Out APIS... By Just
| Asking A Chatbot Instead Of Reading The Manual"
| ofrzeta wrote:
| Unfortunately it's not like every API has a Fine Manual(tm).
| mwkaufma wrote:
| If so, then you have Two Problems
| flowerbreeze wrote:
| My favourite approach to documentation is the "4 kinds of
| documentation" - whether it's about an API, a library or anything
| else. I think it's a very clean way of explaining "good/poor"
| documentation.
|
| In a nutshell, which type of documentation we need depends on the
| goal we have. Any API missing one of the kinds of documentation
| will feel like it is missing something. Once I read about it,
| I've been noticing how the documentation I like tends to have all
| these aspects covered.
|
| https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o...
| footy wrote:
| I don't understand why people who think like this get (or want to
| get) jobs as software developers
|
| It's clearly not enjoyable for them so why doesn't the author
| pivot to something else and stop doing things they hate? It's
| weird
| frizlab wrote:
| Me neither, but it does explain why AI is so popular...
| another_twist wrote:
| Because the time investment isnt worth it most of the time.
| Unless its a widely used framework / library its worth no ones
| time to try and understand API docs, each and every component
| and then deal with some genius patterns thrown here and here.
| Its a skill that has low market value so sharpening it isnt
| worth it.
| frizlab wrote:
| Tangentially related, I did a project (forked, but fully rewrote)
| to be able to avoid the Package.swift file for single file
| projects like these. [1]
|
| The general idea is a bit like uv if I have understood uv
| correctly. Basically you do your imports normally and add a
| comment next to them that tells where the imports should be
| found. Then instead of running your project through swift
| directly you run it through swift-sh (or `swift sh`, swift will
| find the `swift-sh` binary automatically, just like git does for
| plugins). swift-sh will download and compile the dependencies,
| then add the proper options to swift so it will know where to
| find them.
|
| It is even possible to add a regular shebang to swift-sh at the
| beginning of the file, chmod +x it, and just run it like a
| regular script!
|
| Or use swift-sh to compile it.
|
| (And installing swift-sh itself is as easy as `brew install
| xcode-actions/tap/swift-sh`.)
|
| [1] https://github.com/xcode-actions/swift-sh
___________________________________________________________________
(page generated 2026-01-14 23:01 UTC)