

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

Oauth fragmentation? API interoperability? Data portability? Documentation? Terms of Service? Combining APIs? Other issues?
======
saurik
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.

~~~
tadfisher
> 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?

~~~
saurik
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".)

------
cscharenberg
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.

------
dburge
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.

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

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

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

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

------
RobSpectre
Authentication. Hands down.

~~~
saiko-chriskun
This.

------
ohashi
Getting unexpected results.

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

~~~
ohashi
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.

