For companies that operate ecommerce sites, APIs (application programming interfaces) play a crucial role. APIs allow ecommerce sites to share their applications’ functionality and data with business partners — in other words, to fully engage in ecommerce.
Not surprisingly, ecommerce companies dedicate significant resources to creating and testing these APIs. But in many cases, they pay too little attention to what is essentially the last mile: the ecommerce API documentation that potential partners’ developers rely on. This critical user group relies on the documentation in order to evaluate, test, and integrate the ecommerce site’s APIs into their own operations.
In fact, all too often, ecommerce companies task their API developers with writing this documentation themselves. This might seem like a reasonable solution, given that these developers literally wrote the API code — and after all, they’re already on the company’s payroll. But it’s not the best approach, for at least two major reasons.
First, any time a developer spends working on API documentation is time they can’t spend developing software, which is what they were hired to do. Second, writing documentation is not what API developers are best at, so the documentation they produce may be incomplete or confusing to users of the API.
When API documentation is done right, however, it can address a range of challenges and needs, and even give an organization a competitive edge, as explained below.
Well-written ecommerce API documentation …
- … is designed for multiple audiences. All API documentation aims to help developers integrate their own company’s apps with that of the ecommerce site. But well-written API documentation is presented in a way that the less technical audiences will also appreciate and find useful. For example, such elements as clarity of language and inclusion of relevant use cases can help a broader audience understand ways that a given API will benefit their own customers. These other audiences could potentially include system developers, product managers or CTOs. All of these stakeholders want to be sure that your site, and its APIs, are going to meet their requirements.
- … functions as a self-service resource for users. The most effective API documentation is that which meets the needs of users without requiring any additional handholding or follow-up, particularly on the part of your API developers. That means documentation that is not only accurate, complete, and clearly written, but also based on use cases that speak to specific, real-world needs in the marketplace.
- … is written using the latest industry standard. To be most useful to API developers, this documentation needs to be written to meet the latest standard — which currently is Open API/Swagger. What’s more, in many cases organizations retain their API documentation for years, making it essential to make sure it’s done right the first time.
- … helps to attract and onboard new users. One frequently-overlooked impact of good API documentation is its role in attracting and promoting user adoption by new business partners. Remember, when a company is considering your site as a potential ecommerce platform, their review of your API documentation is more than a “kick-the-tires” exercise. They want to see if your API will actually work with their platform and do what they need it to, so the more your documentation can answer that, the better. Your documentation should also include instructional/marketing language that lets potential business partners know exactly what to do as the next step if they want to sign on to a formal relationship.
API documentation: A technical deliverable that punches above its weight
Given the many ways that well-written API documentation can help ecommerce companies, it’s worth taking a second look at how one approaches the task. Finding a partner with knowledge of the critical roles ecommerce API documentation can play, and one who is skilled in the technical processes of creating it and updating it, can make a significant difference in a company’s ability to attract and win new business.