Ernesto Ramirez

July 11, 2014

Today’s post comes to use from Anne Wright and Eric Blue. Both Anne and Eric are longtime contributors to many different QS projects, most recently Anne has been involved with Fluxtream and Eric with Traqs.me. In our work we’ve constantly run into more technical questions and both Anne and Eric has proven to be invaluable resources of knowledge and information about how data flows in and out of the self-tracking systems we all enjoy using. We were happy to have them both at the 2014 Quantified Self Europe Conference where they co-led a breakout session on Best Practices in QS APIs. This discussion is highly important to us and the wider QS community and we invite you to participate on the QS Forum.

Best Practices in QS APIs
Anne Wright 

Before the breakout Eric and I sorted through the existing API forum discussion threads for what issues we should highlight. We found the following three major issues:

• Account binding/Authorization: OAuth2
• Time handling: unambiguous, UTC or localtime + TZ for each point
• Incremental sync support

We started the session by introducing ourselves and having everyone introduce themselves briefly and say if their interest was as an API consumer, producer, or both. We had a good mix of people with interests in each sphere.

After introductions, Eric and I talked a bit about the three main topics: why they’re important, and where we see the current situation. Then we started taking questions and comments from the group. During the discussion we added two more things to the board:

• The suggestion of encouraging the use of the ISO 8601 with TZ time format
• The importance of API producers having a good way to notify partners about API changes, and being transparent and consistent in its use

One attendee expressed the desire that the same type of measure from different sources, such as steps, should be comparable via some scaling factor and that we should be told enough to compute that scaling factor. This topic always seems to come up in discussions of APIs and multiple data sources. Eric and I expressed the opinion that that type of expectation is a trap, and there are too many qualitative differences in the behavior of different implementations to pretend they’re comparable. Eric gave the example of a site letting people compare and compete for who walks more in a given group, if this site wants to pretend different data sources are comparable, they would need to consider their own value system in deciding how to weight measures from different devices. I also stressed the importance of maintaining the provenance of where and when data came from when its moved from place to place or compared.

On the topic of maintaining data provenance, which I’d also mentioned in the aggregation breakout: a participant from DLR, the German space agency, came up afterwards and told me that there’s actually a formal community with conferences that cares about this issues. It might be good to get better connections between them and our QS API community.

The topic of background logging on smartphones came up. A attendee from SenseOS said that they’d figured out how to get an app that logs ambient sound levels and other sensor data on iOS through the app store on the second try.

At some point, after it seemed there weren’t any major objections to the main topics written on the board, I asked everyone to raise their right hand, put their left over their heart, and vow that if they’re involved in creating APIs that they’d try hard to do those right, as discussed during the session. They did so vow. 🙂

After the conference, one of the attendees even contacted me, said he went right to his development team to “spread the religion about UTC, oAuth2 and syncing.” He said they were ok with most of it, but that there was some pushback about OAuth2 based on this post. I told him what I saw happening with OAuth2 and a link to a good rebuttal I found to that post. So, at least our efforts are yielding fruit with at least one of the attendees.

We are thankful to Anne and Eric for leading such a great session at the conference. If you’re interested in taking part in and advancing our discussion around QS APIs and Data Flows we invite you to participate: 

You can sign up for the QS Toolmakers List. 
You can take part in ongoing discussions in the API Forum Thread .
And lastly, you can comment on this particular breakout discussion here.