Designing a ReSTful API

— 2 minute read

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)