4 ms·
Ask HN: 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<Type> like in Rust
I guess, a strict api documentation standard would help tremendously to save quite some debugging time.
- throwaway888abc 5y agohttps://swagger.io/specification/ https://swagger.io/specification/
- quambene 5y agoBut 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 5y agoSo 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 5y agoOne is json schema. The other very good one is stripe API docs.
- rocketpastsix 5y agoJSON Schema is not documentation, it's a schema for data validation in requests and responses.
- is_true 5y agoHe 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 5y agoWhat 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 5y agoOpenAPI 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 5y agoBecause 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 5y ago> 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 5y agoDepends 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 5y agoThat's why I like GraphQL, where you have a typed schema (including nullability) and get the documentation for free.
- Aperocky 5y agohttps://xkcd.com/927/ https://xkcd.com/927/
- matt_s 5y agoThis 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.
- samuel_478 5y agoThanks for sharing. I found a lot of interesting information here. A really good post, very thankful and helpful. https://www.mygiftcardsite.bid/ https://www.mygiftcardsite.bid/
- moasda 5y agoI 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.