Section on API keys

[konklone]

At @seanherron's suggestion, I added a section on API keys.

It explicitly doesn't take a position on whether or not an API should use keys, but says that if an API uses keys, it should allow unauthenticated use of the API under reasonable rate limits.

Feedback desired on this one before merge. (This is a PR to the existing #27 PR, to the rewrite branch.) /cc @arowla @kaitlin especially.

[arowla]

For any of our APIs which use api.data.gov, there may not be an option to not have a key. A demo key, yes, but no key, no. So it might be good to put something in there about allowing people to experiment with either a demo key or no key.

To give a bit more background, FBOpen uses HTTP auth between our production API server and api.data.gov, so api.data.gov is the only party that has the keys to our API. There is therefore no way to access it without going through api.data.gov, and api.data.gov requires at least a demo api key.

Edit: Actually, I was slightly wrong on this. Use of API keys is configurable on api.data.gov. It's just that if you have them turned on to 'required' as we do, then you can't follow the advice of this document. Requiring keys also appears to be the default setting.

[konklone]

Got it, I wasn't aware of how api.data.gov works in that regard (exactly what I was hoping to learn).

Is requiring API keys for FBopen something your team feels strongly about, or was it more of a default choice?

[gbinal]

cc @gui for his thoughts, too.

Regardless of the specific application at fbopen, I do like saying that there should be basic access without registering. I'm a fan of the demo key or no key way of putting it.

[GUI]

api.data.gov has two main options: API keys are required or they are optional. Up until recently, it wasn't possible to rate limit those two scenarios differently, but with the release of OpenFDA, we added the ability to have different rate limits depending on whether or not users provide an API key or not. So now you can set API keys to be optional, but then give API key users higher rate limits than key-less users. I think this opens up the ability to do what you're describing here.

As mentioned, though, we had previously achieved the same type of thing by providing a special "DEMO_KEY" API key in all our documentation examples. The "DEMO_KEY" was simply an API key that had super low rate limits for that key. This approach has always been supported on api.data.gov, so that's how most of the APIs there currently function. Now that we support different rate limits for keyed vs keyless access, we could technically transition to that approach, but unless others feel strongly, I wouldn't anticipate us switching away from the DEMO_KEY approach in the near term (but again, if others feel differently, we're certainly open to suggestions).

More generally, I'm also a big supporter of allowing users to experiment with public APIs before signing up. I think both approaches--a demo key or lower keyless rate limits--largely achieve the same thing for API consumers. So maybe we just leave the guidance at something broad like what Gray said? There should be basic access without registering (but whether that's a demo key or no key, I don't really care). Does something like that seem reasonable, or do you think we want to prescribe the specific approach to take in this guidance?

[GUI]

Oh, and if we do care about the nitty-gritty between these two options (demo keys vs no keys), then you can join me in the weeds...

I think the different approaches perhaps differ very, very subtly. My original thinking was that something like "DEMO_KEY" acts almost like a big "TODO" in your URL--it'll work for playing around, but it's obvious it's not intended for real usage. Whereas, by not having a key at all in your example URLs, it's perhaps not as obvious that you should signup for your own key for real production use. In my mind, these different approaches are maybe related to this bit you have in this PR:

Allowing a certain level of normal, production use of the API, without enforcing advance registration by clients, may also be a product goal.

If production use without a key is a goal, then I think supporting no keys with reasonable rate limits is probably more appropriate (this is sort of like what Google did with V3 of their Geocoding API, and like what OpenFDA does in allowing 1,000 requests per day without a key). However, if that is not a goal, and you want to encourage all users to signup for a key after some initial experimenting, then I think a demo key approach might drive more users towards signing up by being more in your face (I don't have any proof of this, so this is probably more of a usability question, but this strategy is at least reflected in api.data.gov's demo key having much lower rate limits at only 60 requests per IP per day).

But again, in practice, I think these different approaches largely achieve the same thing (basic access without registering), and I don't really care which approach people take. At this point, I'm just yapping about inane subtleties..

[konklone]

I just reworded the section slightly in https://github.com/18F/api-standards/commit/29c313d6c992ba3d6c9e7bc8c54a264c7b359f08 to bring out the second point, about normal production use, a bit more clearly.

I do think demo keys are still more of a hindrance to newcomers than no key - I say this from the experience of running people new to APIs through APIs that I've built that require an API key. Having to always juggle an extra query string parameter adds complexity to the experience (submitting it as an HTTP header wouldn't make it any easier in that case).

But either way, it sounds like we're all on the same page about supporting easy demo use, and that api.data.gov has the rate limiting controls to support it. So barring objection, I think this one's on its way to a merge.

[konklone]

OK, without objection, merging. Thanks, everyone!