Ask HN: REST API Design Guidelines?

7 points by Jim_Neath 16y ago ↗ HN

I'm about to embark on designing an API for my startup. Are there any guidelines available online regarding things like:

- Which response codes should be returned - How errors should be handled - How the xml/json should be structured - How to handle authentication

Or can someone point me in the direction of a particularly well thought out REST API in the wild, that I can learn from?

4 comments

[ 1.5 ms ] story [ 24.2 ms ] thread

joelg87 16y ago ↗

This took some finding but I read your question and remembered coming across one particular article which made a lot of things clear for me when I was looking into building the API for my startup.

Check out "Get Your API Right" by Trek - http://wonderfullyflawed.com/2009/07/02/get-your-api-right.h...

Jim_Neath 16y ago ↗

Cheers, I'll have a read

vog 16y ago ↗

The classic document on this topic is Richardson's Maturity Model, which is quite well and compactly explained by Fowler in his article:

http://martinfowler.com/articles/richardsonMaturityModel.htm...

exline 16y ago ↗

I believe the Twitter API is one of the most widely used API's and would be a good resource. I really like their documentation, it makes integration a lot easier to have it well defined.

Also a huge plus with most API's is a test/development environment. This depends on what the product/service is, but in some cases this is a huge issue.