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

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