search

interagent / http-api-design

HTTP API design guide extracted from work on the Heroku Platform API
https://geemus.gitbooks.io/http-api-design/content/en/
Other
13.69k stars 1.07k forks source link

include more examples for main points #70

Open geemus opened 9 years ago

geemus commented 9 years ago

ie https://github.com/WhiteHouse/api-standards does a good job of listing examples (and counter-examples) for a number of points, which may help clarify.

bjeanes commented 9 years ago

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 commented 9 years ago

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

snowwolf007cn commented 9 years ago

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

bjeanes commented 9 years ago

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 commented 9 years ago

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

frankieroberto commented 9 years ago

@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 commented 9 years ago

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 commented 9 years ago

@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 commented 9 years ago

@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?