beeminder/apidocs

Beeminder API Reference

Beeminder API Documentation

This repository contains the source for the website of the Beeminder API Reference https://api.beeminder.com.

To Do

• More prominent link to Beeminder
• [for bee] Possibly update links to api in beeminder/beeminder to have target=blank

Contributing

If you're working on building something with our API and you run into confusion, we'd love to hear about it! If something's not clear in the docs, or something's not working as you expect it to, it might be us, not you! If you do find something that needs clarification or is just plain wrong, we'd love a pull request with fixes or edits.

Prerequisites

You're going to need:

• Linux or OS X — Windows may work, but is unsupported.
• Ruby, version 2.2.5 or newer
• Bundler — If Ruby is already installed, but the bundle command doesn't work, just run gem install bundler in a terminal.

Getting Set Up

1. Fork this repository on Github.
2. Clone your forked repository (not our original one) to your hard drive with git clone https://github.com/YOURUSERNAME/apidocs.git
3. cd apidocs
4. Initialize and start Slate. You can either do this locally, or with Vagrant:

# either run this to run locally
bundle install
bundle exec middleman server

# OR run this to run with vagrant
vagrant up

You can now see the docs at http://localhost:4567. Whoa! That was fast!

Submitting

Once you've made your changes, you can submit a pull request to beeminder/apidocs!

Deploying changes to the docs

(For beeminder/apidocs owners)

1. Commit changes and push to the master branch at beeminder/apidocs (or accept / merge pull request)
2. Run ./deploy.sh

• Do not touch the gh-pages branch
• Double check if api.beeminder.com is still available.[1]

[1] There was a problem where the custom domain setting was getting unset every time we deployed. It looks like I've successfully fixed it now, but if you check after deploy and the subdomain is broken (e.g. you get redirect to the github pages url) then go quickly into https://github.com/beeminder/apidocs/settings and re-add "api.beeminder.com" under 'Custom domain').

Need Help? Found a bug?

Submit an issue, or email [email protected] if you need any help.

The Beeminder api docs are created with Slate. Check it out at lord.github.io/slate.

apidocs's Issues

purge slate

I opened #12 with the first round, but there is more (see "Initialize and start Slate" in the readme).

Also, is Windows actually somehow unsupported or is it just something remaining from Slate?

Clarify that mathishard is an option

HT Tobben from the Discord:

Small addition that would be useful in the api documentation: It is not obvious (at least to me an hour ago) that goaldate, goalval, and rate can be blank. An explicit reference to the mathishard alternative could be useful, since a new user would probably try the former values first.

Add info how one may obtain token with permission to change slugs (goalnames)

https://api.beeminder.com/#putgoal mentions that goal_type can not be changed, has no similar info about slugs

https://api.beeminder.com/#personal-authentication-token has info how to obtain one but no hint how to get one that will not throw this error:

Exception: API request failed with code 422: {"errors":{"slug":["You do not have permission to change goal slugs."]}}

Use the font Stripe uses

Document 422-errors

https://forum.beeminder.com/t/document-api-422-errors/11245/2

POST /users/u/goals/g/datapoints/create_all.json, incorrect return type

See #9 for previous work on this subject.

POST /users/u/goals/g/datapoints/create_all.json is still incorrectly documenting the return type. Based on my last observation, it

• returns an array of datapoints if you submit a non empty list of datapoints,
• returns an object if you submit an empty list of datapoints:

{
  "errors" : [
  ],
  "successes" : [
  ]
}

The docs incorrectly state:

Returns A list of successfully created Datapoints. Or, in the case of any errors, you will receive an object with two lists, successes, and errors.

Feature: replace "slug" by "goalname" and "title" by "goal description"

According to email conversation "slug" and "title" is an old deprecated version.

At least mentioning new forms in docs would be useful, maybe also allow new for in field names.

If this is a question or feature request, make sure to:

• The title starts with Question: or Feature:.

If this is an bug report, not a question, make sure to:

• I'm not running Windows (which is unsupported), or if I am, I can confirm this issue appears on another platform, or Vagrant.
• This issue appears in the latest dev branch.
• I've included my browser and Ruby version in this issue.

integery is gone, but not in the apidocs

integery (boolean): Assume that the units must be integer values. Used for things like limsum.

See http://api.beeminder.com/#attributes-2 - this seems clearly outdated. Not sure is just docs problem or is API itself also affected. But probably API should warnings / errors.

If this is an bug report, not a question, make sure to:

• I'm not running Windows (which is unsupported), or if I am, I can confirm this issue appears on another platform, or Vagrant.
• I've included my browser and Ruby version in this issue.

Mozilla Firefox 71.0

ruby 2.5.7p206 (2019-10-01 revision 67816) [x86_64-linux-gnu]

autodata (string): The name of automatic data source, if this goal has one. Will be null for manual goals.

listed here
http://api.beeminder.com/#goal

Bug:
documentation claims this is null for manual goals

but it appears to be empty string (and not nil) for manually sourced goals after removing healthkit

unclear rate parameter

http://api.beeminder.com/#attributes-2

"rate (number): The slope of the (final section of the) yellow brick road."

Is it a rate per day? Especially in context of http://api.beeminder.com/#creategoal it seems weird, compared to UI where you have both number and "per day/week/...".

Is rate supposed to be converted to a per day value?

ruby --version ruby 2.5.7p206 (2019-10-01 revision 67816) [x86_64-linux-gnu]
ruby2.6 --version ruby 2.6.5p114 (2019-10-01 revision 67812) [x86_64-linux-gnu]
Firefox 70.0.1 (64-bit)

https://github.com/beeminder/apidocs/commits/dev - dev branch appears to be outdated, so I skipped "This issue appears in the latest dev branch".

If this is an bug report, not a question, make sure to:

• I'm not running Windows (which is unsupported), or if I am, I can confirm this issue appears on another platform, or Vagrant.
• This issue appears in the latest dev branch.
• I've included my browser and Ruby version in this issue.

datapoints_count, diff_since, etc. very unclear

the documentation around datapoints_count and diff_since etc is super unclear. we only mention them i think re the user resource, but you can send them on the goal_resource, and anyway, I don't think we're at all exhaustive in explaining how to use them.

'frontburner' still exists in example text

Noticed today, after trying to figure out why we were getting a bunch of api requests that include 'frontburner' in them:

remove that shit!

Make the left column the width Stripe uses

Compare:

• https://stripe.com/docs/api
• http://beeminder.com/api

Inaccurate doc for datapoint creation

See forum comment

A user noted, while troubleshooting creating one datapoint vs creating many, that what the api/backend accepted and what the api doc describes do not match.

Bring them in sync.

Add "safesum" and deprecate "limsum" and "headsum"

See http://beeminder.com/changelog#3358

created_at field seems missing

I see it in https://www.beeminder.com/api/v1/users/matkoniecz/goals/$GOALNAME/datapoints.json?auth_token=$AUTH_TOKEN but not in http://api.beeminder.com/#attributes-3

I guess that it is creation date of the datapoint?

(Possibly) inaccurate "returns" for when creating multiple datapoints

When a client POSTs datapoints to the API (using https://www.beeminder.com/api/v1/users/me/goals/SLUG/datapoints/create_all.json), the response appears to be an array of the created datapoints which were submitted. This was surprising as the documentation suggests this would have been "the last created datapoint" rather than what actually is, what is - IMO - an intuitive response with all of the involved datapoints.

apidocs/source/index.html.md

Lines 984 to 986 in 9f4a690

	### Returns
	The last created [Datapoint](#datapoint).

Which shape is expected to be returned?

P.S. I'm combing through these pages while working on an API client, happy to drop issues as they crop up or open a pull request if that's preferred!

Question: how can I create goal with specified initial penalty?

If this is a question or feature request, make sure to:

• The title starts with Question: or Feature:.

http://api.beeminder.com/#creategoal has no info how one may create a goal with specified penalty.

For example, using browser UI I may create goal starting from 0$ or 5$ or more, here goals by default start from $1 an I see no option to change that.

Question: Add info how one may invalidate access tokens

https://api.beeminder.com/#personal-authentication-token has info how to obtain one but no hint how to invalidate it.

Maybe changing password would work (not sure, not tested).

In case of leaked access token invalidation would be useful for obvious reasons.

Clarify updateable fields

HT rperce in https://forum.beeminder.com/t/api-deadline/10666/4?u=dreev

it might be worth putting a blurb on the "update" api pages that explicitly only calls out what (if any) attributes can't be updated and says that the rest can—right now there's a list of the "special" ones like roadall, but it also includes a few "normal" parameters (like title) that make it look like ones not mentioned (like deadline) can't be updated.