As noted in an overview from Red Hat, the technical definition of an API, which stands for “Application Programming Interface,” is a "set of definitions and protocols for building and integrating application software." API is a term that’s been popping up more and more in this age of digital transformation. Understanding what APIs truly are—and what they can do—can help companies large and small unlock the potential of this powerful tool.
When I’m asked for my personal definition of an API, I compare application programming interfaces to something we’re all familiar with: user interfaces. Simply put, a user interface involves a human interfacing with a program by clicking a mouse or striking a keyboard, while an API involves a program interfacing with another program.
As a manufacturer, building an API takes time. There’s quite a bit of thought on the front end, and a lot of testing before the API is released.
A very common example of an API that’s fairly ubiquitous is the familiar weather snippet. A search engine such as Google will provide a small box on your screen with a forecast—but that doesn’t mean Google is compiling weather data. They’re reaching out to a third party, and as one program queries another, the human using the search engine and glancing at the temperature is receiving customized data based on his or her location.
Who’s the End User?
An important distinction to keep in mind: The end user of an API is a program. Naturally, a human will be the beneficiary of those communications, but it’s critical to note that if two programs are speaking with one another and one program changes, the other will need to be updated to understand the new behavior. New versions of APIs tend to “layer” atop old ones as they’re introduced, since the updates often build on previous functionality.
[How Crestron's Sightline Experience Achieves Equitable Hybrid Meeting Spaces]
In our world here at Crestron, the human benefitting from the work performed by an API could have their IT department query Crestron’s XiO Cloud to provide info so they can make dashboards and reports. In the case of Crestron’s DM NVX—which, of course, has its own API—the benefit is that if the IT department wanted to query it using something other than a Crestron control system, they could. All the functions that an API performs are running seamlessly in the background, and when the right API is integrated properly, you’ll always get the results you’re expecting in a given situation.
Here's a real-world illustration: One of the things that dealers or integrators can do is build a tool on top of XiO Cloud to combine the data from XiO Cloud and, for example, Microsoft Exchange. This could then provide the customer with a view into the functionality of both, tying all of these disparate systems together. If a room’s been scheduled via Exchange, then XiO Cloud can confirm that said room was actually occupied at the time it was booked and not going unused—and that’s the kind of data that can make any business vastly more efficient.
As a manufacturer, building an API takes time. There’s quite a bit of thought on the front end, and a lot of testing before the API is released. The first thing you need to be aware of is every possible use-case for that API. You’ve got to make sure that you’re not “painted into a corner,” so the product is flexible enough to accommodate additions to the API without breaking its existing behavior.
Creation Considerations
To achieve the desired end result—a product that’s very intuitive—we undertake a complex development process. How complex? When it comes to proper API design, there are several considerations that we must keep top-of mind:
• Make sure the API is well documented, easy to read, and easy to work with—the API should be as close to self-explanatory as possible. You always want to be sure an API is structured in such a way that if someone knows how to use one API call (that is, a request for data), then the other calls will follow the same pattern.
• Create an API that isn’t overly complicated. If the finished design is something in which every function requires 12 calls, the design must be simplified so that fewer calls are required.
• Build an API so that it can’t be misused. Don’t expose things on any interface to people who may not have the proper rights.
• Stay up to date with the versioning because new features (and often optimizations) will be added to newer APIs.
• Ensure that any kind of error conditions are processed correctly. At Crestron, we define all of this in API documentation, so if you're asking for values of a device that doesn't exist, we'll give you a specific, consistent error message. If an error condition isn’t processed correctly, that leads to a situation where the API is being bombarded with requests, and nothing is resolved.
[Tried-and-True Wins the AV Heart and Business]
For example, JSON (JavaScript Object Notation) is used often to communicate between APIs—and JSON allows you to send just a partial object. (For the uninitiated, JSON defines a small set of formatting rules that is easy for programs to interpret.) If you haven’t written your code in such a way that you can handle partial objects, you’ll begin to see error messages. Do those messages precisely identify the issue? Is the device broken or is it actually nonexistent?
When we’ve finished and tested the API—and attempted to break it in every way we can think of—there’s one last step. When it’s finally ready for implementation, one of the ways we perform real-world testing is by using our own API in the background. We’re actually a consumer of our own API—and I can’t think of a better way to ensure that it’s functioning properly.
