Question

I’m trying to develop a simple REST API. I’m still trying to understand the basic architectural paradigms for it. I need some help with the following:

1. “Resources” should be nouns, right? So, I should have “user”, not “getUser”, right?

2. I’ve seen this approach in some APIs: http://www.domain.com/users/ (returns list), http://www.domain.com/users/user (do something specific to a user). Is this approach good?

3. In most examples I’ve seen, the input and output values are usually just name/value pairs (e.g. color=’red’). What if I wanted to send or return something more complex than that? Am I forced to deal with XML only?

4. Assume a PUT to /user/ method to add a new user to the system. What would be a good format for input parameter (assume the only fields needed are ‘username’ and ‘password’)? What would be a good response if the user is successful? What if the user has failed (and I want to return a descriptive error message)?

5. What is a good & simple approach to authentication & authorization? I’d like to restrict most of the methods to users who have “logged in” successfully. Is passing username/password at each call OK? Is passing a token considered more secured (if so, how should this be implemented in terms of expiration, etc.)?

Answer 1

For point 1, yes. Nouns are expected.

For point 2, I’d expect /users to give me a list of users. I’d expect /users/123 to give me a particular user.

For point 3, you can return anything. Your client can specify what it wants. e.g. text/xml, application/json etc. by using an HTTP request header, and you should comply as much as you can with that request (although you may only handle, say, text/xml – that would be reasonable in a lot of situations).

For point 4, I’d expect POST to create a new user. PUT would update an existing object. For reporting success or errors, you should be using the existing HTTP success/error codes. e.g. 200 OK. See this SO answer for more info.