Building a simple RESTful api

Question

I'm wanting to make an API quickly, following REST principles - for a simple web application I've built. The first place the API will be used is to interface with an iPhone app. The API only needs handle a few basic calls, but all require authentication, nothing is public data.

• login/authenticate user
• get list of records in users group
• get list again, only those that have changed (newly added or updated)
• update record

So, following REST principles, would I setup the uri scheme?:

• mysite.com/api/auth (POST?)
• mysite.com/api/users (GET)
• mysite.com/api/update (POST?)

and the responses will be in XML to begin with, JSON too later.

1. On the website, users login with email and password. Should I let them get a 'token' on their profile page to pass with every api request? (would make the stand alone '/auth' URI resource redundant).

2. Best practices for structuring the response xml? It seems like with REST, that you should return either 200 ok and the XML or actual proper status codes i.e. 401 etc

Any general pointers appreciated.

Answer 1

You're generally on the right track. The URI scheme should be based around the idea of resources and you should use an appropriate method to do the work.

So, GET to retrieve info. POST (Or maybe PUT) to create/change resources. DELETE for well, delete. And HEAD to check the metadata.

The structure of your XML doesn't have much to do with a RESTful API, assuming it doesn't require state management. That said, you have the right idea. If it's a good request, return the desired XML (for a GET request) and status code 200. If it's a bad request, you may also, and in some cases needed to, return something other than just the status code. Basically, get familiar with the HTTP spec and follow it as closely as possible.

Answer 2

1- for auth, you might want to consider something like http-basic, or digest auth (note - basic in particular is insecure if not over https)

for the urls scheme:

• /api/auth is not needed if you leverage basic or digest.
• /api/group/groupname/ is probably more canonical
• /api/update would generally be done as /api/users/username (POST) with the new data added - the resource is the user - POST is the verb
• otherwise, basically your API looks sane, much depends on whether groups are hierarchical, and users must live in a group - if so, your urls should reflect that and be navigable.

2- status codes should reflect status - 200 for OK, 401 for access denied, 404 for not found, 500 for error processing. Generally you should only return an XML record if you have a good request

Answer 3

Authentication in an API always works by sending some authenticating token in the request header. I.e., even when using the separate /auth login approach, you would return some token, possibly a cookie, back to the user, which would need to be send together with every request.

HTTP already provides a dedicated header for this purpose though: Authorization.
The most basic HTTP "Authorization" is HTTP Basic access authentication:

Authorization : Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Digest Authentication is another, more secure, scheme. You can use this header field for any form of authentication you want though, even your custom implemented authentication.

Authorization : MyCustomAuthentication foo:bar:n293f82jn398n9r

You could send the aforementioned login token in this field. Or you could employ a request signing scheme, in which certain request fields are hashed together with the password of the user, basically sending the password without sending the password (similar to digest authentication, but you can use something better than md5). That obliterates the separate login step. AWS employs this method.

For an API in general, make good use of the HTTP status codes to indicate what is happening.