Just wanted to start by saying this was my first real experience creating an API, though I did have a vague understanding of how they worked before. API stands for application programming interface and while I could probably try to come up with my own explanation of what an API is used for, wikipedia probably has the most suitable explanation:
An Application Programming Interface (API) is a particular set of rules and specifications that a software program can follow to access and make use of the services and resources provided by another particular software program that implements that API. It serves as an interface between different software programs and facilitates their interaction, similar to the way the user interface facilitates interaction between humans and computers.
Given that explanation, APIs are good in the sense that they can simplify design, allow for multiple implementations, and enable scaling. Though there are a lot of benefits to using an API, there are some drawbacks such as: increased implementation complexity, boundaries created by limits of the API, and using an API can cost performance/optimization. Given that information, we are designing an API for the iHale system because we feel it will simplify the interactions between the home's sensors and other interfaces. Developing an API for the home will make it easy to develop applications on multiple platforms that can interface with the home.
REST API
The first step in designing the Team Kai's iHale API was to develop a REST based API for communicating with the home's sensors. Our goal was to create a API that would simplify the communication between our iHale system and the home's systems. As a result, we came up with an XML representation for each system, that makes it easy to view and modify the system's states.
 |
| iHale REST API |
Java API
Along with creating a REST API, we created a Java API which will use the data retrieved using the REST API. The XML retrieved from the home's systems will be parsed and placed into Java objects which can then be stored and manipulated. By creating a Java API for iHale, as mentioned above, it will be very easy for external developers to come along and develop applications for the home. Eventually we plan to expand the system developed here to include a front-end, back-end, and simulator (at least till we have access to the actual sensor readings). Currently the Java API we have developed contains an object class for each system (e.g. aquaponics, hvac, lighting) and methods for storing, retrieving, and deleting of these objects. By using these object classes, as long as we are provide with all of the parameters, we can generate xml to PUT to the systems.
Development Experience
I think that the most unexpected and hardest part of developing our REST API was figuring out how everything fit together; it was really tough trying to understand how the systems of the home would interact with the iHale system. Eventually we determined that the iHale system would be able to communicate with each of the home's systems using a generic XML representation. After solving how the communication worked between systems worked, we had to carefully figure out what data readings/states we would need from each system. Developing the Java API was pretty straight forward compared to the REST API; the biggest issue was fixing minor errors so the system would pass verify (findbugs, pmd, checkstyle, etc).
As well as being the hardest part, understanding how everything fit together was probably the most interesting part of the development process. We had to actually sit down and draw diagrams and write out what variables we would need for each system; doing this probably took the most brainpower. Looking through the sample api was also interesting as it allowed me to see how the API interacted with the front-end and back-end.
Deliverables
