Ernesto Ramirez

June 7, 2013

Today’s guest post come to us from Eric Jain, the lead developer behind Zenobase and a wonderful contributor to our community. 

At last month’s QS Europe 2013 conference, developers gathered at a breakout session to compile a list of common obstacles encountered when using the APIs of popular, QS-related services. We hope that this list of obstacles will be useful to toolmakers who have developed APIs for their tools or are planning to provide such APIs.

1. No API, or incomplete APIs that exposes only aggregate data, and not the actual data that was recorded.
2. Custom authentication mechanisms (instead of e.g. OAuth), or custom extensions (e.g. for refreshing tokens with OAuth 1.0a).
3. OAuth tokens that expire.
4. Timestamps that lack time zone offsets: Some applications need to know how much time has elapsed between two data points (not possible if all times are local), or what e.g. the hour of the day was (not possible if all times are converted to UTC).
5. Can’t retrieve data points going back more than a few days or weeks, because at least one separate request has to be made for each day, instead of being able to use a begin/end timestamp and offset/limit parameters.
6.  Numbers that don’t retain their precision (1 != 1.0 != 1.00), or are changed due to unit conversion (71kg = 156.528lbs = 70.9999kg?).
7. No SSL, or SSL with a certificate that is not widely supported.
8. Data that lacks unique identifies (for track-ability, or doesn’t include its provenance (if obtained from another service).
9. No sandbox with test data for APIs that expose data from hardware devices.
10. No dedicated channel for advance notifications of API changes.

This list is by no means complete, but rather a starting point that we hope will kick off a discussion around best practices.