I always had a general idea of what APIs were, but the latest module on API design really helped to define what exactly they are for me. First and foremost, I didn't even know what the acronym stood for: Application Programming Interface. I really just saw APIs (most specifically the Java API in particular) as a toolset that I could easily call upon to do magic for me. I never gave it too much thought as to where the magic came from.
After watching Joshua Bloch (of Google fame) give this presentation on good API design, I have a much better understanding of the steps and thought process that goes into designing an API.
Things I've learned about API development:
- if in doubt, leave it out; it's always easier to add to an API than to remove something from one. This is what's known as the pain of deprecation.
- naming conventions in API implementation should be really straightforward; you ought to be able to read an API without too much documentation (should read almost like prose)
- the planning of API's are of extreme importance. A good API can be a godsend of efficiency to a company and a poor one can be a total disaster, and impossible to overcome.
We have started upon our own API development with regard to the Solar Decathlon Team Hawaii project.
The Solar House being built by the University of Hawaii Team is made up of several subsystems (Aquaponics, HVAC, Lighting, etc.), all of which will feed information from sensors to an intermediary system named iHale. iHale is based on the REST architecture and is the backend system that allows for the exchange of information between the house subsystems and client applications (mobile browsers, desktop apps, etc.).
Here's a diagram of the iHale system and how it interacts with other systems within the house:
Team Name: Nai'a (Dolphin)
REST API: Here
Java API: Here
Looking back:
The hardest thing I think was grappling with the magnitude of the entire project and completely understanding the requirements. The option of sending commands to the house subsystems also complicated things to a small extent. Prior projects had basically involved tweaking existing mockup eclipse projects, but this project involved applying the previous three modules to create our own structure.
This did, however, give me much more insight into how API development progresses, and how you try to not only code to get things done, but for the most flexibility and understandability in the future. I think I have a much clearer understanding of REST now that we have concrete resources (the sensors and database objects) and verbs (getting the data from the sensors and pushing commands to the house subsystems).
Also, in an attempt to streamline the API, we did not include a database to hold a record of actions committed by the home user. We were unsure how this data would be used; we can definitely see a use for historical state data, but the added functionality and overhead of adding another database table didn't seem to be worthwhile. If the need comes up, the system has the flexibility to add this if necessary.
