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

9 points | by quambene 9 days ago


  • rocketpastsix 9 days ago
    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 9 days ago
      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 8 days 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 8 days ago
          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 9 days ago
        That's why I like GraphQL, where you have a typed schema (including nullability) and get the documentation for free.
        • capuno 9 days ago
          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.
          • moasda 8 days ago
            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.

            • streetcat1 9 days ago
              One is json schema. The other very good one is stripe API docs.
              • rocketpastsix 9 days ago
                JSON Schema is not documentation, it's a schema for data validation in requests and responses.
                • is_true 8 days ago
                  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
                • quambene 9 days ago
                  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 8 days ago
                    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
                • Aperocky 9 days ago
                  • matt_s 8 days ago
                    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.

                  • samuel_478 8 days ago
                    Thanks for sharing. I found a lot of interesting information here. A really good post, very thankful and helpful.