Assignment A07: API Design for iHale

The acronym API gets thrown around a lot these days and it is intended that a programmer know exactly what it entails. API stands for "Application Programming Interface." This interface sets the foundations to describe the usage of an application. This sounds simple enough, but this is a very difficult practice. To create a good API, one must consider all the needs of the user.

The API must provide flexibility and functionality, especially for cases that the designer has not thought of yet (although they should try to think of everything). The task becomes exponentially hard when the user doesn't even know what they want, thus the programmer must guess. And this was the case in A07: API Design for iHale.

As mentioned in previous blogs, my team and I are responsible for designing the the system for a self sustaining house. It can be assumed that there are sensors to monitor various environments belonging to the house and actuators to invoke changes on these respective environments. And at this point of time, we are still guessing at the requirements of the engineers.

According to Joshua Bloch, an employee of Google, a good API must be:

• Easy to learn
• Easy to use, even without documentation
• Hard to misuse
• Easy to read and maintain code that uses it
• Sufficiently powerful to satisfy requirements
• Easy to evolve
• Appropriate to audience

So in a sense, the programmer is trapped by his/her API once it is created. Thus, we have to think carefully at how we would like to design the API surrounding the system behind the inner workings of the house. We have to plan for a future that we can't readily picture and make sure our application has the flexibility to placate to unforeseen needs/problems.

It is with this intention that we designed our Java API and Restlet API. For the task of designing our Java API, we need to create objects that can be readily used to interact with the front end of the system and the Berkley DB backend. For the task of designing our Restlet API, we need to create resources to interact with sensors and actuators contained by various environments of the house. Since as of yet there is no agreed standard for each system, we tried to abstractly generalize the requirements.

In the restlet (http) interaction between the simulated house and iHale, we generalized that there would be multiple systems to be monitored. Each system could contain multiple environments. For example, there could be an aquaponics system which could contain a fish-tank environment and a plant-tank environment. Each of these environments could be monitored by sensors and modified by actuators. For another example, a sensor could monitor pH (or consolidate pH and temperature, etc) and an actuator could provide measures to offset pH (i.e. adding base/acid). These sensors and actuators will be our resource objects which will be interacted with by the back end.


As for the Java API, we provide a MasterSystemObject that will act as a proxy/boundary for any interaction with the house simulation. It will contain subsystem objects which in turn will contain environments. The environments will contain devices that will either be sensors or actuators. It should be again noted that the user of the Java API will not see these subclasses. The MasterSystemObject will provide intuitive methods to allow the programmers to invoke changes as they see fit.

All in all, I'm not sure if we met the required criteria for our API design as many of our fellow class mates went in a completely different direction. This was not an easy task by any means. Design is a very hard subject to teach and often takes a lot of experience to make good design decisions.