Once upon a time, someone told me, “Your software is as good as your documentation.” I can’t agree more!
In an era where interoperability is the key to success – where you can’t even think about building something from scratch – having superior documentation means killing the market. And when it comes to the Internet of Things space, this topic is even more relevant. Internet of Things speaks to integration among multiple, heterogeneous entities: devices, applications, systems. Such integrations MUST be done via APIs. Someone must develop the glue – the code that connects to a third-party API provider and consumes such API. How can this task be tackled without efficient documentation? Very simply, it’s impossible!
Given the rising priority of these needs, people have started to re-think how to deliver good documentation efficiently. The old days, when there was the “User Manual” (with as many pages as possible to show you have pervasive documentation) are gone – luckily. Pick 100 random developers, and ask them how they approach the task of consuming a third-party API. I bet my shirt that at least 98 will open Google and check for an example of consumption. THIS IS THE KEY – well documented, and easily searchable API’s!!
Documentation means enabling other people to understand your software interface in order to use it. The documentation is effective if the user is able to consume the given service (subject of the documentation) achieving the desired result. Efficient documentation is measured by the time that the user actually spends to get the task done.
There are certainly some cases in which you are also interested in the high-level concepts, the philosophy behind some choices, etc., but pragmatically you just need the 20 lines of code that get you connected to the service! In an ideal world,:
- the user can quickly find the correct API to use,
- the interface of the API is crystal clear in terms of input format and expected output, and
- the authentication strategy (if applicable) is very easy to implement on the client side.
Sadly, the reality is that this scenario rarely exists.
API consumers need tools to shorten dramatically the learning time of a service interface – tools to solve the issue of poor and unsearchable documentation. Once such tools are available, anyone can follow this simple procedure:
1) Find the correct API to consume.
- Prerequisite for the API provider: each method should be semantically described – a short description of what the method does
- Requirement of the tools: an easy search function, given the semantics of the API to consume
2) Understand the API interface – the necessary inputs and the expected outputs.
- Prerequisite for the API provider: the interface of each method should be syntactically described with a short discussion of each input parameter (purpose of the parameter, which range of values is allowed, optional effects when the parameter assumes particular values, etc.), and a description of the output (both successful and erroneous/exceptional invocations)
- Requirement of the tools: ability to “decorate” the API with the information regarding input/output parameters
3) Securely connect to the API: understand the authentication/authorization framework.
- Prerequisite for the API provider: wherever possible, use standard frameworks with exhaustive, configurable client libraries; always consider the resources available at client side and the performance vs. the required level of security
- Requirement of the tools: easy ability to “decorate” the API with reference to the security frameworks adopted, or to link the API with other examples on how to integrate the security into the API invocation.
Obviously, the tools should also be API-provider-friendly, in the sense that the API provider should quickly generate the documentation structure e.g. automatic tests are usually excellent sources for examples on how to consume some API; the tool should be able to receive automatic tests in input and turn them into valuable documentation. In this way, the production of the documentation will no longer require a huge effort from the API developer, and, far better, the documentation will be kept in sync very easily!
As an IoT Architect, I should quickly understand whether an API provider gives my team the functionalities we need to perform our tasks. As an IoT Manager, I must consider the effort required of my team to integrate any particular provider. Without effective tools, this activity is quite a nightmare; trying to reuse existing tools, bending them to achieve the result, is nasty. Luckily, some tools – for personal and corporate use – are bubbling out. We will learn how to use them effectively – just like we did with IDEs!
Cristiano Ghersi, PhD
Cristiano is a long-time developer and architect and is the founder of Snip2Code, Inc.