Vox Pop

Development — Software, Personal, or Otherwise

This website is being deprecated. All archives and new writing is being moved over to MatthewReinbold.com.

Document First

Describing the Cart Before Hitching the Horse

After the initial requirements meetings it was time to begin writing the API. I knew what needed to be done: provide uniform, predictable, and easy access to a variety of distinct, back-end systems. My system would return tidy JSON. But how would it be structured?

I wrestled with this . On one hand, I could use the existing table and field names from the relational databases I am connecting to. However, the naming conventions are not consistent. Where repeatable conventions did exist they might make sense in the context of the other database tables but were less then clear outside of them. With other developers soon to be building off my work it wasn't like I could just call "oops" a month after launch and swap things out.

Test first is a long standing best practice. Mobile first has also risen to prominence with the fine work by Luke W. What helped me overcome my quandary, however, was to document first.

Putting the cart before the horse isn't wise. That's why it is an adage. However, what if the cart hasn't been built yet? Wouldn't you describe the kind of cart you'd want to have your horse pull before starting work? Taking this approach I started outlining things as they should be. I changed to thinking about the best way a stable of apps would be able to pull the information along. I asked what made the most sense for them:

the ask: We have deals in the system and want to display a list of them. Clicking on an item in the list will take the user to a screen showing only the clicked deal and a rich level of detail about it.

the response: In one database the information for the list is called "eventTitle". In another its "promo". In yet another the information that would be used in this situation is called "Short Description". Since we're talking about deals and the return structure should be somewhat self documenting, let's call this parameter "dealTitle".

Writing the document first also had benefit of illuminating things that hadn't been thought about in the ramp-up meetings:

If we:
  • Allow the user to add events to their personal favorites and …
  • Those events have expiration dates and …
  • We only show non-expired events in general pick lists then …
Do we still expect expired events to appear in a user's favorites?

That's not to say that the API documentation was cast into bronze before any work was started. Some areas, like user profiles, were an iterative process of discovery in what worked best between the iPhone developer, the project manager, and I. However, writing to a strong idea of what an ideal syntax would be rather than hoping to piecemeal a consistent solution together proved to be quite beneficial.