APIs: What Are The Common Obstacles?


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.

This entry was posted in Discussions and tagged , , , , . Bookmark the permalink.

2 Responses to APIs: What Are The Common Obstacles?

  1. 11. APIs that return nondescript error messages like “Invalid Request”. Help developers figure it out quicker with “that user has not allowed *blah* data access”
    12. Log of outages. No shame — Facebook, Google, Amazon, everyone goes down. Help developers figure out if errors in their logs are on their end, or as a result of a blip outage. Something like: http://status.aws.amazon.com/ helps devs build more robust connector code.
    13. Batched queries can be amazing performance boosters for both provider and consumer saving bandwidth and number of API calls. For example: https://developers.facebook.com/docs/reference/api/batch/
    14. Per user, rather than per-application API rate limits (if needed at all). At some point if an app becomes popular it will stop functioning, likely without warning.
    15. XML vs JSON. The death of XML has been greatly exaggerated. In some cases, it is easier to parse a subset of a response out XML because nested nodes are named. I do this in Fitbit.NET wrapper library (https://github.com/aarondcoleman/Fitbit.NET). If possible, provide both XML and JSON outputs like Fitbit does (example: https://wiki.fitbit.com/display/API/API-Get-Recent-Activities). The religious debate of curly braces vs angle brackets will rage on forever.
    16. Cache transparency — If a request is being served from a cached copy that has any possibility of being stale (even by seconds), include the cache time so a client app can decide if it is significant to the user if this data might have more current info coming shortly. Extra credit if an API includes the next cache refresh.

  2. Eric Jain says:

    Good points!

    Regarding error messages: I know it can be a lot of work to return helpful error messages. But at the very least I need to know whose fault the error was (4xx vs 5xx).

    Regarding outages: At the very least, it’s helpful to have a status check URL, so I can suspend all requests to a service while it’s down.

    Regarding batching: Best would be if the API was designed to not require a zillion requests in the first place (see #5)!

    Can you explain what you mean by “named nested nodes” in XML vs JSON?

Leave a Reply to Aaron Coleman Cancel reply

Your email address will not be published. Required fields are marked *


You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

Notify me of followup comments via e-mail. You can also subscribe without commenting.