Bad API documentation: Why, and what you can do about it

 In CloudRail

There is one problem with most APIs. The documentation sucks.

It takes a lot of work to write decent documentation. Even though requires a similar skill to programming. Clarity. Organisation. Conciseness.

The problem is teams trying to think of what the public will need. The team can refer to past conversations and internal documentations. When trying to show off the API to the Internet community, these items can not be displayed as well.

Solving Bad Documentation Headaches

The best way to solve the problems of needing to use an API with bad API, (we are a little biased), is by using CloudRail. CloudRail is a universal API that allows you to select integrations (APIs) that you require to use in your application and set both which particular functions you wish to use, and the way you want to both input and output data from these functions, allowing you to completely define which data types you need in your program. In short, it’s like you could go straight up to the API creators and slap them silly until they make the APIs that you want. Using CloudRail also makes adding multiple APIs into your app development incredibly simple. It is just a matter of selecting the new integration in the free CloudRail workbench tool.

Receive our newsletter

  • Get updates about CloudRail
  • Read about new Services
  • Get insights in IoT and Cloud topics

Start using CloudRail today

So, what makes Bad API documentation?

One indicator of bad API documentation is more time spent describing functions, instead of datatypes. For example, the Philips Hue API can actually be quite complicated. There are different requirements for colours, different to other colour codes. This requirement is something that API Documenters rarely think about.

Even though Datatypes are more important than functions, functions also need to be explained. It is not useful for any programmer to try and work out how a function works based on little more than a name and a short description. Error codes, expected output, and other such functions are required to be known. Otherwise, programming for the API becomes a matter of trying out different functions. Then looking at the output to work out what’s working. And adjusting. And repeat. Multiple times a day.

Related to functions, many API documentation writers also don’t think about setting out their functions in a logical way for programmers. For example, many APIs don’t list what functions HAVE to be used. For example certain kinds of authentication functions. Additionally, others don’t consider how important it is to set out which functions are needed to be used for which case. For example, there might be one function that allows a user to write to a spreadsheet with a data array. But when adding a new row, instead of using this function, there is instead a less memory intensive “addNewRow()” . If the API documentation doesn’t point out this, then a programmer may always use the memory-intensive method.

The real problem of bad documentation

The real problem with bad documentation is that it stifles the progress that developers can do on their applications. With bad documentation, it is impossible for developers to be able to integrate new APIs into their applications as fast as they would want to. Meaning that apps simply can’t develop killer features as fast as they should be able to. Making all apps amazing is something that we at CloudRail strongly believe in. This is why we created the CloudRail universal API and provide it completely free of charge.

Recent Posts