As technology develops, it’s important to keep APIs up to date. Alan Chow explores what makes a good API and how it can make everyone’s life easier.

Communications protocols or APIs (Application Programming Interface) are a set of definitions and protocols for building and integrating application software.

I recently read an article written by Toine C Leerentveld who is the director of product management for cloud and control at Crestron, on this topic and it’s inspired me to write a similar article from my point of view.

Having worked in this industry for more than 15 years now, I have seen APIs change as technology has changed – some changes for the good and others for the bad.

In our business, a good API or a bad API can make or break a system and it is important that manufacturers adopt creation of a good API, provide complete documentation of it and, lastly, maintain it.

At Chowmain, we write integrations (also called drivers, modules, profiles, plugins, quick apps, etc.) for a large number of control and home automation systems (Control4, Crestron, Crestron Home, ELAN, Fibaro, Q-SYS, RTI, Savant and URC, to be precise). These systems have different architectures, use different languages and have their own software development kits.

A good API should be flexible to a point where all systems, regardless of limitations, should be able to integrate their product range.

So what makes a good API? From a control system standpoint, a good API should have several qualities.

Be simple

If an API is overly complicated then it takes the software developer more time to understand how it works and it may also require pre-design testing, carried out on actual hardware, before designing the architecture of the integration.

In addition, a complicated API will lead to more mistakes in the integration due to misconceptions of how it works, along with extra time required to develop the software, and additional overheads on the system to deal with the complicated design.

Where possible, use existing technology to build the APIs like REST, websocket, JSON and XML, and make the data structure simple.

Be local

In recent years, there have been many manufacturers who have adopted online cloud-based APIs for their products. They do this because their smart phone app uses this API already and it makes it easier for them to maintain.

However, from a control system standpoint, it is not desirable for several reasons. Internet disruptions can cause a loss of control for example, or latency occurring due to the fact that the system has to go out through the internet to the cloud servers and back again into the home.

Cloud based APIs can also break easier than local APIs as a single API update can cause all integrations to stop working. With local based APIs, we don’t have these issues.

Be secure

It is important to ensure that you protect the customer’s home by securing your API via authentication and, potentially, data encryption, though not at the expense of providing an easy-to-integrate API.

By using standard security methods and encryption ciphers you can protect the data from prying eyes and also protect the system from unauthorised users.

Be efficient

Polling is bad. Instantaneous feedback is good. When connecting to a good API the control system will poll a single time upon initial connection to the device to get the current state.

After, it should maintain a persistent connection (or register for a callback) to listen to changes from the device. The device will send the messages to the control system upon state change. This ensures that network traffic is minimised, CPU load is lower on the control systems, and we don’t miss important timely events.

Be descriptive

Good documentation ensures that the software developer makes minimal mistakes, designs the integration seamlessly and produces the software at a faster rate. What does good documentation look like? It provides as much information as possible.

Some examples include:

• A description of how to connect to the device/gateway/service
  • IP Address / Port Number
  • RS232 / RS485 baud rates
• How to authenticate with the device/gateway/service
  • Username / Password
  • Basic / Digest
  • OAuth
  • Token
  • Nothing
• If it is a gateway device – How to pull in the system architecture – number of devices, device types, device names, etc.
• Provide capabilities on the devices (e.g. on/off, dim, colour, colour temp, min color temp, max color temp, min temperature, max temperature, min set point, max set point, available HVAC modes, available fan modes, etc)
• Provide command and queries with examples along with what is sent and what will be received along with all possible values descriptions (for strings), minimum and maximum ranges for the values (for numbers) along with descriptions of what the commands do and what the values are for.

Be responsible

With new products and features being added to a manufacturer’s range, APIs get updated. A responsible manufacturer will ensure that any API update provided to a device (usually via firmware update) will be backwards compatible.

Deprecation of an API or a particular command or query in an API can break the integration so it must be handled correctly.

If the deprecation is unavoidable then the manufacturer has a responsibility to reach out to anyone using the API to provide them with the new API. They also need to provide adequate time for the developer to produce an update or new integration using the new API. At this stage it is important for the developer and the manufacturer to notify customers that this deprecation is happening and what the upgrade path is and how long they have until the deprecation happens.

In summary, a good API can make life easier for everyone involved including the manufacturer, software developer, integrator and the end user, whereas a bad API will cause pain for everyone.

By taking a little more time to design the API properly it will ensure that everyone is happy and that the experience is smooth.