Testing APIs in eCommerce Sites Part 1
From Tribal Knowledge to API Documentation
eCommerce takes salesmanship to its logical end point: selling products and services with no more customer interaction than browsing a website. The continuous effort to capture and hold the customer’s interest that this requires has placed a significant strain on the concept of software quality. To support a successful, large scale eCommerce business means that the company’s software developers have to quickly roll out a reliable and scalable site, complete with a Web Services API at the business startup, and be prepared to make major updates to it on a weekly or bi-weekly basis.
Large eCommerce sites often grow from humble beginnings to major operations very quickly. The original architectural vision may pass through several hands and end up being held in the memories of two or three key software engineers. This ‘Tribal Knowledge’ creates problems for rapidly growing companies. Key engineers are constantly distracted from their primary task of developing new system features and capabilities to answer trivial ‘where’s this’ and ‘how do I do that’ questions. There is little proactive system maintenance.
Creating an API Documentation Tool
One of the more creative solutions to the dilemma of “I don’t have time to fix it… how in the world can I document it?” is the concept of creating a granular process wherein each task performed in maintenance of any aspect of an API also results in direct documentation of that aspect.
Much of this already exists in the form of communications between the marketing, development and test arms of the company when a fix has to be described and proven to work. Properly managed, these communications can result in each fix also creating a short document that explains that fix in the context of the system’s operation. With a little collection and editing, these ‘fix notes’ become a living document describing the structure and operation of the system API that is being supported.
A handy tool for doing this is the wiki. According to Wikipedia, one of the largest such sites on the Internet, “A wiki is a website that allows the easy creation and editing of any number of interlinked web pages via a web browser using a simplified markup language or a WYSIWYG text editor.” Users of this information make up the community of collaborative contributors to it.
To be a useful API documentation tool, it requires an editor/moderator who maintains the structure of the system and validates the quality of its content.
Whatever the methodology used, documentation of all aspects of an API, from its design to its maintenance, will pay off all out of proportion to the effort put into getting that priceless information recorded in the first place.
Contact us for more information on our API testing services.