Table of Contents
Manage Everything Through the Critic API
Developers can now interact with the Critic API to access everything you see in the Critic web portal. Notably, the Critic API now supports retrieval and management of Reports, Products, Organizations, and Memberships. To get started, review the Critic API documentation.
Our Approach to Documentation is Special
The Critic API documentation looks a bit different compared to most API documentation you’ll find. To provide API documentation that is always correct, I chose to generate documentation from our test cases. Specifically, I am using the Avocado gem (avocado-docs) to produce updated documentation every time I deploy a change to Critic. As outlined below, this practice provides several benefits over traditional documentation.
Documentation is Always Accurate
If the Critic API documentation says something, you can believe it. Since documentation is generated based on passing test cases, only features that work as described are present in the documentation. If something changes in the system, it will change in the documentation. You don’t have to trust me to manually track changes and update the documentation. It will happen automatically. You never have to hold your breath when testing an API for the first time. That is, the Critic API works as advertised.
Writing Documentation is Undesirable
Developers who enjoy documenting what they’ve created are rare. It feels like unnecessary work because the benefits are only apparent to other people. By making documentation a generated outcome of doing a good job (testing!), we eliminate the grunt work.
Testing is a Natural Part of Product Development
At times, I’ve had difficulty convincing developers of the importance of automated testing. However, practically every developer has experienced frustration with API documentation. Typos, mismatched endpoint URLs, unclear parameters, and unknown response formats make integration a guessing game. What if we could make all of those frustrations go away?
By using tests to document your API, those frustrations are gone. Additionally, testing has its own benefits. Tested software is less likely to have defects. Tests also validate a developer’s thinking. A proper test case validates functionality as far as the developer understands it. While this doesn’t guarantee that a developer builds the right thing, it does guarantee that they build the thing well. When your team is practicing automated testing, you as a product owner receive these tremendous benefits.
Automating an Important Aspect of New Releases
Your product should always have appropriate documentation. In traditional workflows, documentation updates can be as arduous as the product release itself. However, by generating Critic’s API documentation, I’ve been able to maintain a one-click deployment process. When a new change to my product is released, so is the updated documentation. I don’t even have to think about it. It just happens. And more importantly, it always works.
Is Our Documentation Perfect?
Of course, not everything can be properly captured by generated documentation. There are some aspects of integration that felt better left to a getting started guide. However, I generated the Critic API documentation much faster and more accurately than anything I could have done by hand.
Are You Ready to Build?
Review the REST API documentation to see how you can take ownership of all aspects of your customer feedback experience. If you need help getting started or have ideas you’d like to share, contact us to start a conversation.