API version 2 planning and wishlist

Tech
1

This is a wiki for starting to sketch version 2 of the Beeminder API. Huge thanks to @insti for help in thinking this through so far.

Here are some principles we may want to adopt:

Wishlist

All queries should return json.

Requests should be able to be made using json.
(This has the advantage of not requiring array data such as road matrices and datapoints to be json encoded and then url encoded as in v1)

e.g.:

curl -X POST -H "application/json" -d '{"slug": "mygoal", "road":[["20150213",null,9]]}' http://api.bmndr.com/etc

Normalised road matrix. [placeholder - I’ll expand on this when I get more time. @insti]

More helpful error messages that give indications about what might be wrong with the submitted data.

This post is a placeholder. Edit at will, including deleting this line when it’s less placeholdy!

1 Like
2

Can we agree to keep the option of having a user token that will authenticate just you that can be copied and pasted from any logged in browser? It makes it really easy to write a script to do something quick.

3 Likes
3

I.e., keep personal auth as well as oauth, definitely.

2 Likes
4

I’ve only using the API to post data, but don’t recall running into any issues. The only weirdness was having to URL-encode the JSON. The implicit grant OAuth workflow works well for me, but could confuse some people who are used to the more complicated authorization code grant workflow.

1 Like
5

Thoughts from trying to use the API over the last week:

  • API doesn’t seem to export the units for a goal. I mean the human-editable string of what the units are.

  • diff_since doesn’t seem to be honored. I’m setting diff_since=1423785600 and getting data for February 5.

  • Concerning that various objects return random extra fields. For example, datapoints contain ‘canonical’ and ‘daystamp’ which are undocumented. Users have fields like ‘fitbit_enabled’ (or something like that). Maybe this is just how JSON APIs are, but I grew up on protobuf and I miss being able to know for damn sure what is going to come popping out of the server.

  • Frustrating that the API seems to be providing the bare minimum for you to “do it yourself” when it comes to calculations rather than enabling quick access to data like “What is the value of the goal right now?” or “What is the height of the YBR on date [X]?”. Yes it’s all computable, but I’ve got hundreds of lines of python to crunch all this and it’s full of bugs apparently. :-/

  • Doubly frustrating that the goal time zone and runits are baked into the road data instead of specifying a standard format for the road and letting tz/runits be a transform layer on top of it. If you want to manipulate the road, you have to boil the tz/runits out of it first, and then put them back.

3 Likes
6

Feature request for wishlist: it would be great if the API included the Access-Control-Allow-Origin header in its responses so browsers wouldn’t throw the cross-origin request error when calling the API.

3 Likes
7

I just tried to use the “create a datapoint” endpoint and specified the fields timestamp, value, and comment. It returned the following:

{"errors":{"measured_at":["can't be blank"],"daystamp":["can't be blank"]}}

The documentation doesn’t mention a measured_at field anywhere and it also doesn’t say that daystamp “can’t be blank” when specifying a timestamp.

8

Also, the documentation isn’t very clear on what timezone the timestamps are in (e.g. the user’s timezone or UTC?).

9

As I understand it:

Timestamp is independent of timezone, being the number of seconds since the unix epoch.

Daystamp is local to the goal’s view of what day it is, which may not correspond to the user’s view of what day it is…

10

There are several features that are not currently accessible through the API. In particular, I don’t think it is possible to change the pledge cap. A new version should have more or less the same features as the web interface.

2 Likes