HACKER Q&A
📣 quambene

Why is there no standard for API documentation?


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 like in Rust

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

  👤 gregjor Accepted Answer ✓
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.
👤 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.
👤 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.

👤 nivertech
That's why I like GraphQL, where you have a typed schema (including nullability) and get the documentation for free.
👤 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.
👤 streetcat1
One is json schema. The other very good one is stripe API docs.
👤 throwaway888abc
https://swagger.io/specification/
👤 Aperocky
https://xkcd.com/927/