Just as diners complain about restaurants - “The food is terrible and the portions are too small!” - developers bemoan API documentation: we want it to be better, and we want more of it. Despite modern technology’s reliance on APIs to bridge gaps between services and platforms, the actual process of developing and understanding APIs is fraught with gaps in communication among people, teams and business verticals.
Most developers aren’t going to learn an API thoroughly - which is typically fine, as a developer who has only a top-level understanding of an API can still use it. APIs are often treated like remote methods or functions with a few extra hoops to jump through. In these cases, developers don’t need a full-scale onboarding; it’s enough to do a quick Google search on the problem and implement a solution in a few minutes. In turn, a popular public API with unique features (like Google Maps or Square), will create documentation to address this, designed for external users who want all their information on one page.
Alternatively, if you are contracting with another company to build a legacy integration or working with another team to produce a complex service, you probably want an API that tells a story in depth. Paths of knowledge can build from page to page – not just establishing the functionality and implementation behind features, but also the intention, reasoning and significance to a larger whole.
So, why these two extremes: quick and focused on short solutions vs. detailed and telling a complete story? One reason for these differences is that public API documentation is written to inform the uninitiated, while internal documentation is often both created and consumed by those close to the project.
For the internal API, this is a blessing and a curse. When you write good internal documentation, your audience is more than the user - it’s any developer (including you) that will commit on this project in the future. Good internal docs leverage this, allowing narrative and intention to form alongside instruction. Many enterprise services have been twisted by generations of hacky additions, and too much tech infrastructure is held together by bubblegum and sticky tape, so good documentation is especially crucial. Internal documentation allows you to describe what you were trying to do when you made a change, in case someone comes along later and needs to apply more tape and gum.
Bad documentation, conversely, lags behind its product and often justifies rather than explains the layers of mistakes that went into the final product. This is more than just common – the developers who complain about such documentation are as guilty of creating it as anyone else! This is why developers shrink at the term “legacy integration.” Bad documentation makes me wonder if I can trust the back-end code, and can be the reason your team might spend a week rebuilding a working service - because although it seems to work, no one knows how.
So how do some APIs end up with great docs and some with terrible ones? It comes down to communication. Teams that communicate well deal with this hurdle through consistent reality checks into the API from outside the development team, often in the form of functional demos and other shareable artifacts. They actually score documentation as a task rather than let it linger as a vague afterthought of the build. If you aren’t documenting as you go, you can often lose the “why” of an integration while scrambling to deliver on the “how.” You can leverage different tools to avoid these pitfalls during build, and one of the best tools for developing APIs is Postman.
Postman lets you bridge gaps in knowledge not only between developers and users of an API, but also technical and non-technical team members. Chances are your developers already use Postman to test their work. With luck, they saved some of these tests. And, with even more luck, they commented on them. Postman automatically generates artifacts to help you understand your API as you work, so those tests and comments are immediately ready to publish as documentation.
Everyone learns differently. If you learn by reading, the auto-generated documentation feature in Postman will be extremely helpful. If you’re more the hands-on type, downloading a collection - a machine-readable description of the API - lets you manipulate the API firsthand to see how it behaves. If you need context on how others are using the API, Workspaces is a feature that allows teams to share and collaborate on work. The simple UI makes all of this accessible, even to those who don’t know how to code.
Postman’s sharing and testing features allow insight into code changes as progress is made: no more back and forth between departments, and no more sitting in the dark as to what the devs are actually working on. The end result of these learning pathways is not just better documentation, but also a more robust solution.
Even teams with public APIs can leverage Postman as a learning tool. Supplementing API documentation with a set of interactive example requests is a great way to introduce end users to what your service can do. Plus, people playing around and solving problems for themselves may even reduce the load on your support team. There are already plenty of teams leveraging the Postman API Network to do just that.
Improving API documentation benefits everyone - now and throughout the entire API lifecycle.