Ask HN: What's the biggest pain in the a** when you're using APIs? | Hacker News Reader

Ask HN: What's the biggest pain in the a** when you're using APIs?

3 pointsmehdim14 comments

Oauth fragmentation? API interoperability? Data portability? Documentation? Terms of Service? Combining APIs? Other issues?

View on HN

Not handling error semantics well: sometimes things fail, and thinking through what happens when they do fail is one of the more complex problems in programming. I can easily just write more code to handle authentication or interoperability (I'm a programmer: I write code; I have no fear of writing a lot of code), I have never found APIs with "poor documentation" to be a serious issue, and the terms of service on APIs are usually fine.

The real problem is that when the API fails I get back what... one of a massive set of possible error conditions with opaque code numbers and some random english string that I guess I have to render all the way out to the user in the hope that they understand it or that it is even relevant to them? Are new error states going to be added in the future? Who even caused the error, so I know who to give it to: was it me, was it the user, or was it a natural disaster?

What happens if the response from your server to mine is lost after you've already committed the change; is there an idempotent way I can verify what happened? Is it ever the case that I can get back a success and the request didn't actually work after the fact? If so, how do I figure out what requests failed, and am I stuck occasionally making, quite literally, a few million requests to check the status of every transaction I've ever previously executed?

If you are making callbacks to my server (ugh, this always sucks, and should be avoided except as a notification to cause an early poll: you can design systems that are both efficient in requests and don't require push) are you retrying failures? What do you even consider to be a failure? Again, is there an idempotent way that I can determine whether I've already seen the callback when retried? When retries happen, what happens to the ordering between messages?

Most web APIs these days seem to believe "oh, I'll make some really pretty documentation for a single call that shouldn't be able to fail anyway, and yeah... webhooks!", and the result is a horrible mishmash of garbage that, when it fails, simply "fails" in a way that pretty much requires a human to go interact with the state of the entire system and figure out what may have been forgotten or lost, or worse: how to fix the result.

> What happens if the response from your server to mine is lost after you've already committed the change; is there an idempotent way I can verify what happened?

What is the "right way" to handle this? Say I'm building a REST API, and a user POSTs to a collection, which returns the URL to the posted resource in the Location header. POST in this case isn't idempotent, so what mechanism can I provide for the user to check that this resource was indeed created? A search method?

I am not certain I know the "right way" to deal with this, but a common way that makes my life as a consumer of APIs much easier is to make the API idempotent (if I pass the same request, including a nonce, I get back the exact same result as the earlier request). There are other solutions, though; I will claim that most of them that I have seen, however, involve making the client much more complex (such as a search system, unless the search system allows me to search by the nonce; an example of doing the search solution reasonably is Amazon Payments, and an example of doing the idempotent API reasonably is PayPal v74.0+).

(BTW: the possibly short snippet for my long post might me "API semantics that make it impossible to build a completely automated solution even in the case of failures, either transient or persistent".)

Not giving practical How-To instructions. Reference material in itself is very slow to work with, especially with new development. Documentation needs to include real examples of different calls, and the use of multiple calls to accomplish various tasks.

The best documents give core API references, example calls, multiple calls chained together, and the full back-and-forth HTML exchange data to see authentication and calls working.

I'd have to second the poor documentation is the biggest pain.

Another would be not providing sample code in whatever particular language you might be working in.

In terms of programming against an API, it's having to worry about handling the situations that occur when an API call fails, for example retrying later. You can't assume that the API will always be available when talking about web service type API's.

http://rashkovskii.com/2012/08/19/symapi-api-for-apis/

Poor documentation, leaky abstractions, poorly thought abstractions (requiring multiple calls to the API to accomplish common tasks).

Is it because those services publish a CRUD-like APIs?

Poor documentation is #1. Second is abstracting things into unintuitive objects/calls.

Authentication. Hands down.

This.

Getting unexpected results.

You talk about documentation? unexpected data? Could you elaborate?

It's vague because it's a problem in many areas. It could be a documentation issue. It could be data returned. It could be naming conventions/parameters. I don't like being surprised by a result coming from an API.

Reply on news.ycombinator.com