For the past quarter I've been deeply involved creating a spanking new product for Placewise Media. As discussions went on it was clear that this offering would also require an entirely new API.
The existing Placewise API I built two years ago is aging well. It has easily scaled to feed nearly a hundred different IOS and Android native apps. It also powers a number of externally developed phone apps, populates widgets on 3rd party sites, and syndicates content as part of new revenue possibilities that we couldn't do when we just wrote websites.
That API, however, is shopping center-centric. Given the new product's scope I found myself having to draft a new set of interfaces to support the business objectives. Initially reviewing the first proposed wireframes that my backend systems were to support was daunting. After the necessary "They want to do what now?!" had been offered up to the programming gods I started in the same place that I did with the original RESTful API: with the documentation.
As a sweet post on the Twilio website points out the repercussions of not nailing a technical system's docs are twofold: (1) some fraction of developers who would otherwise have used your product won't and (2) those that do will require more attention from your support team. Given me, myself, and I are likely to be the support team I'd prefer to maximize time doing other things; like practicing my mullet-enabled luggage tricks.
Documenting an API first also means you're programming to an interface, not to an implementation. What language am I going to program in? Java? Ruby on Rails? Python? What algorithm will the recommendation engine use? Collaborative? Content-based? All of those questions still matter - but they only matter to me. The consuming application shouldn't have to worry whether I've used the correct dependency injection. They just care that when they make an HTTP GET method to my URL they always get the canonical list of mullets (for example).
A perfect implementation of the wrong specification is worthless for both the API producer and consumer. If you have a perfect spec but the implementation is lacking only the producer will have the long weekend (but I'm sure I can just throw some more hardware at it, right?).
