API changes in the Yellow Brick Half-Plane New World Order

Tech
1

We anticipate keeping everything backward compatible in the API and won’t intentionally break anything so definitely holler if anything breaks.

But this thread is for @adamwolf and @apb and @bee and me to coordinate on what we want to deprecate and how clients ideally should use the API post-YBHP.

Also a quick sanity check from @mary or other iOS people: does everything about YBHP goals currently seem fine in the iOS app?

Back to tech nerdery…

1. Switching from limsum to safesum

This is orthogonal to YBHP but we’re soon switching from limsum to safesum so might as well make that update to clients while we’re at it.

2. Deciding between tluz and safebuf

At some point we thought that the single canonical thing that clients should care about is tluz (called losedate in the API). It’s the timestamp of when you’ll derail if you don’t add any more data.

Is tluz all we want? Clients need to know the integer number of safe days. Is that easy to derive from the tluz timestamp or do deadlines and timezones make it fraught? Beebrain currently returns the integer number of safe days – safebuf – but we were going to deprecate it? Should we?

How are y’all currently getting number of safe days from the API? The lane field? That obviously needs to die and maybe safebuf is the right thing to replace it with.

Speaking of which…

3. Death to the lane field

The lane field was a way to number the regions of the graph and told you which region the current datapoint was in:

image

(And I guess it could be +3 or more for being further above the road or conceivably -3 or less for being further below the road.)

Could everyone (Adam for Beedroid, Andy for BeemiOS, @malcolm for Complice, @narthur for TaskRatchet… who else?) grep their Beeminder integration code for lane and show me how you’re using it?

I think in the new world order we want to compute a legacy deprecated backwards-compatibility lane field like so:

lane = yaw*(safebuf - (safebuf <= 1 ? 2 : 1))

(UPDATE: The above is implemented for YBHP now.)

4. Clients computing the color themselves

Beebrain currently returns color (either “green”, “blue”, “orange”, or “red”) but that’s not documented in the API and should be deprecated. Clients should derive it themselves from the number of safe days like so:

color = (safebuf < 1 ? "red"    :
         safebuf < 2 ? "orange" :
         safebuf < 3 ? "blue"   : 
         safebuf < 7 ? "green"  : "gray")

Update: Just to try out @grayson’s suggestion, I updated the above to include gray for 7+ days of safety buffer!

3 Likes
2

I haven’t started on the TaskRatchet Beeminder integration, so no worries there.

1 Like
3

Backward-compatible lane field is now deployed! We now fully expect API clients to all keep working fine post-YBHP (except for all the ways we expect that we have failed to expect).

1 Like
4

So far so good for me, but I’m on the beta, so let’s check in with some of the dailies (and others) who are also on iOS to make sure we’re getting a jump on any bugs there that might be portends!

2 Likes
5

Update: safebuf is now officially part of the API (it has been unofficially part of it for a long time).