[shearn89]

As @artanis0 (kind of) mentioned, it'd be great to see a HN post sometime soon called "How to write a good 'REST' API". Or even just some links to good tutorials that could get me (and others) started? I've recently built a DB driven site that could possibly be extended with an API, and it's a good chance to learn something with a purpose behind it!

[poutine]

It's pretty straight forward, just do the following:

- Use HTTP verbs: GET to retrieve one or more objects, POST to create a new object, PUT to update an existing object, DELETE to remove an object.

- Address objects by collection and by individual object: /users/#{user_id} is a specific user you can PUT, GET or DELETE. /users is where you POST to in order to create a new user.

- Use HTTP codes to return the result back to the client (ie HTTP 200 when you get an object, 201 when you successfully POST an object, 404 when you try to GET/UPDATE/DELETE an object that doesn't exist).

- I find it good form to return objects in JSON with the type of object at the top of the data structure, ie {:users => [ #array of users here ]} or {:user => { #single user }}

- Use OAuth or some sort of token system for authenticating the calls, don't use HTTP Auth.

You can get pretty anal about things but if you follow the above you'll have a cleaner API than 90% of the API's out there.

[danellis]

> Use HTTP verbs: GET to retrieve one or more objects, POST to create a new object, PUT to update an existing object, DELETE to remove an object.

You forgot PUT to create a new object and POST to update an existing object.

> Address objects by collection and by individual object: /users/#{user_id} is a specific user

As far as REST is concerned, that doesn't really matter. The important thing is that the client doesn't generate the "/users/#{user_id}" URLs itself, but rather selects a URL from those it has been told about.

> I find it good form to return objects in JSON with the type of object at the top of the data structure, ie {:users => [ #array of users here ]} or {:user => { #single user }}

Apart from the fact that doing this allows for gracefully adding extra information, there's also an important security reason for doing this rather than having an array at the root: http://haacked.com/archive/2008/11/20/anatomy-of-a-subtle-js...

> Use OAuth or some sort of token system for authenticating the calls, don't use HTTP Auth

Why not do both? http://oauth.net/core/1.0/#auth_header

[SimHacker]

A big dumb mistake this api makes is sending commands and object ids via query parameters, instead of making them part of the url. The url should look like a file path that addresses an object -- the path of the objects shouldn't be in a query parameter. Especially when the object you're addressing is a file that has a logical location specified by a path.

[jcromartie]

REST is not about pretty URLs. In fact, you could build a great RESTful API with pretty hideous looking URLs.