include more examples for main points about http-api-design

[bjeanes]

I particularly like "no values in keys" which makes me think of the Heroku config var endpoint (the key in that hash is an important value).

[geemus]

Yeah, I certainly agree with the point (and agree that config-vars are BUSTED).

[snowwolf007cn]

This section 'Programtic REST' is not a good choice. I think in header is better by the way of content-negotiation.

[bjeanes]

My friend @chendo pointed out an interesting use case for putting the version (and I suppose the content type) in the URL: if your API is to be consumed by semi-technical or non-technical people (e.g. integrations with IFTTT/Zapier), having a valid request be trivially valid with nothing but the URL isn't worthless. Nonetheless, for most APIs I think the choices outlined in our design guide are a better starting point.

[snowwolf007cn]

The best way to deal with such occasion is to provide them with a SDK.

[frankieroberto]

@snowwolf007cn or at the very least, the code for a curl or XMLHttpRequest.

That said, I think there's also some benefits to not requiring a version identifier in an HTTP header – for one thing, it means you can link to GET requests and they'll work in a browser.

The .json and .xml suffixes are a fairly widespread convention now too, and FWIW I don't think they're especially un-RESTful (especially if used alongside a non-suffixed version which uses content-negotiation).

[geemus]

I think header for version is still the best default. If it needs to be in the path (for the reasons stated) I think allowing a way to pass it in the query string (similar to how method override works) is a cleaner way to keep it separate but in the URL (vs putting it in host/path). What do you guys think?

Also, updating the title on this. I meant "main points" not "key points" per se. ie I think there are a few decent things in there, not just the keys/values stuff, just wanted to clarify.

[frankieroberto]

@geemus allowing an override in the querystring seems like a reasonable compromise. However I do think there's a reasonable argument for either not-versioning an API, or allowing requests with no version stated to default to the 'latest' one.

[geemus]

@frankieroberto Yeah, I've gone back and forth about that. I think the only case in which I would say it was ok is if there was no versioning (which I'm not sure is tenable). Otherwise you have the situation you describe, where default is latest, which I feel like is problematic because it means that for end users the API could change on them at any time (between two requests even). By requiring the specificity, you avoid surprises (kind of like specifying dependencies in other software, you usually don't just let it update in between web requests or between tests or what have you). Does that help/make sense?