Monday, February 7, 2011

API Design

As a software developer, I have used a number of APIs for programming languages, documentation writing, web frameworks, etc.  Like many who are starting out in the field, I did not think I would ever need to write an API... until now.  Before delving into the details of my experience in API design, let us start with the basics.

API stands for Application Programming Interface.  An example is the Java SE6 API.  An API documents the sets of rules that define how software systems can interact with each other, and the boundaries for what a programmer can do.  For an easy analogy, a LCD TV manual lists all of the possible ways to use the TV, from turning it on via the power button to changing color temperatures via a combination of buttons.  Likewise, an API is the programmers' manual that describes the functions that can be used to do something useful.

APIs are not written only for programming languages, but for a wide variety of technologies including applications, libraries, operating systems, etc.  They are sometimes synonymous to the terms "reference guide" or "reference manual".  The technology for which I have designed and written an API is the iHale system.  The top-level architecture can be visualized as follows:

Diagram of the iHale system.

The iHale API serves as a point of interaction between the house systems, web user interface, repository, and other optional interfaces.  I designed a REST API and a Java API.  The REST API specifies how the different house systems and optional interfaces communicate with the iHale system through HTTP requests and commands.  The Java API specifies how information is stored and retrieved in the repository based on the HTTP requests it receives.

Designing the APIs was not particularly challenging because I had already written user stories and had a sense of what the possible requirements were.  For example, the Aquaponics system would need to support functions to return information pertaining to water volume, temperature, PH, oxygen level, and time of data procurement.  However, this may not fully describe all the fields and functions required for the aquaponics system.

As we make progress on the solar decathlon project in the following weeks, my team and I will gather requirements in greater detail by speaking with the engineers and referring to specification sheets for the sensors and meters that will be used in the house.  As we gain a better understanding of what is possible and what isn't, we will revise and update our API.