Ask HN: REST API Design Guidelines?

7 pointsJim_Neath16y ago4 comments

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

4 comments · 3 top-level

joelg8716y ago· 1 in thread

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_NeathOP16y ago

Cheers, I'll have a read

exline16y 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.

vog16y 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...

j / k navigate · click thread line to collapse