At APIContext, we mainly deal in the analytics of APIs and the corresponding infrastructure that supports them. These traits are easily quantifiable and the results make for simple benchmarking and examination. Another crucial, yet slightly ambiguous attribute is the API’s documentaion. Developers spend countless hours designing and building the APIs that users depend on and love, but they tend to take shortcuts when it comes to documenting. It is easy to argue that the most important piece of UX for this type of product is not actually the Sign-Up, Homepage, or even the SDK download page, but actually the Documentation. It doesn’t matter how useful, time-saving or cool your API is if nobody can figure out how to use it. Below are a couple key best practices for creating and maintaining your Documentation.
Think about your Audience
Stating that an API is a product will not spark much debate, but many don’t think about Documentation also being a product they are selling. When selling a product, knowing your audience is a necessity. If you do not know your audience, you will not be able to craft your language to match that desired target – hell you won’t even know what your desired target market is. Here are some of the main audience members for most API Documentation:
The Red-Eyed Debugger – Tired, grumpy and goal oriented, this user just wants find the source of their issues, fix it, and move on. Much like the Greenhorn, the Debugger wants text that is easy to read, FAQs, but most importantly they want explanations of possible responses and interactive examples.
The Greenhorn Dev – Fresh out of a coding bootcamp, or just a weekend warrior, this user is looking to get started and needs things laid out in a friendly manner. Easily understandable text, copy + paste functionality, tutorials, examples and use cases are highly sought after by this group.
The Top Dog Decision Maker – Be it CEO, CTO, VP of SDET, or any other high level acronym left off the list, this user want the important details and hard facts to better assist them in making decisions. Whether they are scoping out competitors APIs, looking for partnerships, or new ideas, the Decision Maker wants a professional layout, samples of real world usage, interactivity and a concise overview.
The Brain Storming Product Manager – Could I do this? Would that be possible? The Brain-Stormer is always searching around trying to see if a solution exists for the problem they are having. Be it low latency search functionality, a seamless login, or maybe the ability to integrate in predictive analytics. This user is looking for easy to read overviews, real world examples and FAQs on integration.
Utilize Standard API Frameworks
In the past, creating useful API documentation was almost exclusively manual. These archaic publishing problems are now behind us. Online automated API Documentation Frameworks provide extraction for your code base and assist with the grind of writing accurate and articulate guides. Below are 3 of the more popular Frameworks being used today.
Swagger – Swagger UI is a dependency-free collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API. The goal of Swagger is to allow client and documentation systems to stay in sync and update along with the server. The documentation of methods, parameters and models are tightly integrated into the server code, allowing APIs to always stay in sync. With Swagger, deploying managing, and using powerful APIs has never been easier.
API Blueprint – API Blueprint by Apiary gives you awesome tools for your whole API life-cycle. Use it to discuss your API with others. Generate documentation automatically. API Blueprint also allows for anyone on the team to edit and update the documentation, helping keep your specs up to date for users.
RAML – RAML – RESTful API Modeling Language (RAML) is a simple and succinct way of describing practically-RESTful APIs. It encourages reuse, enables discovery and pattern-sharing, and aims for merit-based emergence of best practices. RAML is an open source project based on YAML and JSON that is here to make documentation easy and efficient. RAML lets you put all your API definitions in one place; a single, simple .raml file, which greatly assists with keeping documentation up to date.
Policing your Documentation
All of these tools are meant to make documentation easier, more efficient and accurate. One of the biggest challenges an API might face in market is keeping the documentation up to date, data in sync, thorough yet succinct and precise.
Nothing can kill an APIs reputation faster than poor documentation, whether that’s not having interactive test calls, neglecting to make note of changes that have been made, or simply taking shortcuts leading to incorrect information being distributed. Below are a couple horror stories around this very topic.
- “A database interface where EVERY method is called getData and has no comments and all parameters have the same names. There are about 100 such methods spread over multiple interfaces (all accessing the same database). Have a good time to find out what the one getData does that gets called with one mere int. Most likely something completely different from the one that takes a float…”
- “A core library where the developer removed all comments and even the names of the parameters to obfuscate the library so that people stop using it without asking him (most bugs revolved around people using those functions without knowing what they do)…”
- “I had this guy that gave me the API documentation in a pdf with 50 pages. Horrible to navigate. Couldn’t interact and test calls. Spent a lot of time trying to get the information i needed. Not to mention object structure…”
- “While running some final tests we kept getting error responses and could not figure out why for the life of us. We double and triple checked the documentation, examples, test calls. None of it worked. We finally contacted the provider and after a week or so of them telling us we had it set up wrong, it turned out some major changes were made to the API and the documentation was never updated…”
Finally, APIs can and will change, fixes will be applied, new features added, standards will change. API providers need to be very aware of the impact on 3rd parties of these changes and ensure that they are well communicated and have policies and procedures in place to spot when a potentially ‘breaking change’ is pushed live to existing customers with apps and services deployed in the field. Remember, with something like an iPhone App, a developer cannot push a fix or a patch instantly, the app will need to go through the App Store process which can take a week or more. So be sure to constantly monitor what you have documented and deployed to ensure that your users remain happy.
Conclusion
Saying documentation isn’t sexy is not going to spark debate. It is probably one of the last steps thought through when taking an API to market, and a developers least favorite. However, with the API economy on the rise and new competitors appearing every day, Documentation has never been more import, or easier to do. Utilize an API Documentation tool to help, do it right the first time, don’t take shortcuts, and keep your docs up to date at all times. As stated earlier, It doesn’t matter how useful, time-saving or cool your API is if nobody can figure out how to use it.
Don’t get caught with your stats down! Monitor the performance of your critical APIs with APIContext. Get started TODAY!
