HN Explorer

Ask HN: Why is there no standard for API documentation?

9 points by quambene ↗ HN
I'm currently integrating purchase api for google and apple in my app. And it's quite painful because api documentation is often slightly inaccurate, which is leading to a ton of extra debugging.

Take this apple purchase api documentation for example: https://developer.apple.com/documentation/appstorereceipts/responsebody.

Attribute "is-retryable" is documented as boolean, but in fact it is an integer (0 or 1), which is only explained in the description text.

Also, you almost never get the information if an attribute is nullable (or optional). Why not just document nullable like e.g.

1.) Type (nullable), or 2.) Option<Type> like in Rust

I guess, a strict api documentation standard would help tremendously to save quite some debugging time.

16 comments

[ 3.0 ms ] story [ 53.2 ms ] thread
throwaway888abc
https://swagger.io/specification/
quambene
But it seems this standard is not adopted widely?! To be more accurate, I would have to reformulate my question: Why is there no widely adopted standard for api documentation?
kkirsche
So I work with this field and evangelize OpenAPI at work. The simple fact is, very few developers actually know about it, and the pool of online tutorials that don’t mention it so vast, I think it becomes a problem of scale and knowledge. Some companies use it, VMWare for example uses it for the fusion API documentation. But it’s 100% dependent on having at least a few devs at whatever company who have enough power to push for this as important
streetcat1
One is json schema. The other very good one is stripe API docs.
rocketpastsix
JSON Schema is not documentation, it's a schema for data validation in requests and responses.
is_true
He was talking about docs. JSON's is great, I was trying to make some guys understand and error on the syntax of a pretty big financial institution and after a couple of mails I just send them on of the pictures from the JSON docs and they got what they were doing wrong. The picture was just a diagram of how the parser works
capuno
What about SQL? Not even that has a solid standard; Oracle, Postgres, MySQL... Nothing is compatible! How can we make a standard for something every company has different when we can't even make a standard for databases used by everyone.
rocketpastsix
OpenAPI is making some headway in this area, although its hard to get everyone to standardize around _something_. Especially after people have gone through so many different documentation types such as RAML, Apiary, and others.
gregjor
Because there’s no penalty or cost, and little to no competitive advantage. Only programmers ever see API documentation, and they are not in a position to force better documentation. If good API documentation provides a competitive advantage companies will pay attention to it. Until then they will continue to concentrate on dark mode and emojis.
ezekg
> If good API documentation provides a competitive advantage companies will pay attention to it.

I think this is already happening. I commonly compare API services based on their docs.

For my own API business in particular, I've had numerous customers tell me they chose us because of good documentation.

gregjor
Depends on the service. If the company sells to developers, or requires developers to extend their customer base (e.g. Stripe) they will put more effort in. If developers seem incidental to their service and customers they may not (e.g. Zoom, Google Drive).
nivertech
That's why I like GraphQL, where you have a typed schema (including nullability) and get the documentation for free.
Aperocky
https://xkcd.com/927/
matt_s
This is the only answer right here.

What is the standard for measuring on our planet?

A lot of people can adopt one standard but there are still laggards that won't change so you end up with several standards.

If you have more than 1 standard, there is no standard.

moasda
I face the same problem quite often.

I think that's the reason why some business APIs provide a client library to use the API. Then it's easier to add some checks to avoid misuse of the API.