Designing a ReSTful API

This article from devo.ps has gotten a bit of attention over at hacker news.

  • Design your API for developers first,

  • Use HTTP verbs

  • Use HTTP status codes,

  • Simple URLs for resources: first a noun for the collection, then the item.

  • Use verbs for special actions.

  • Keep errors simple but verbose (and use HTTP codes).

Relying on HTTP status codes and verbs should already help you keep your API calls and responses lean enough. Less crucial, but still useful:

  • JSON first, then extend to other formats if needed and if time permits.
  • Unix time, or you’ll have a bad time.
  • Prepend your URLs with the API version, like /v1/emails/1234.
  • Lowercase everywhere in URLs.

It is a good summary - and I would read with it this older article on kellabyte.com as it goes into more detail.

(and of course, the original academic paper on Representational State Transfer)

Copyright © 2008-present Brendan Graetz