Is there a reason to avoid RESTful APIs? The principles make for better web apps, and you can simplify how you implement them in a number of ways:
URIs refer to real things. Things in your domain like Users, Badges, Documents, Videos. URIs don't contain the actions or other instructional bits of the request. These URIs let your applications talk about things apart from their state and verbs (this is good). This concept is good for usability, and is good for the application as it keeps the URI space neat and tidy.
Returned data refers to other system data. Instead of your application magically knowing about where things are, the data returned from each request knows about data related to it (a User.xml packet might include URIs to their ContactMethods, for example). This moves the knowledge of the system from the application to the data, allowing multiple clients to change their implementation when the data does.
Returned data defines the shape used to send data back to the server. If you get an XML record of a particular shape back for a User, that's what the server expects you to send when updating it. You can simplify this principle by using the same keywords, so when receiving XML, you send POST parameters with the same naming structure.
Actions are separate from the data. The ideal HTTP implementation uses HTTP header actions for manipulating the data:
POST for updating records,
DELETE for deleting them,
GET for viewing them,
OPTIONS for learning about them, and so on. The ideal is not required (as not all clients can easily send HTTP
DELETE messages), but the principle can be simplified into a common set of
GET commands (a common set of variables mapped to those actions).
As for authentication, there are a number of common models used:
- API keys. Your system generates a key to allow 3rd party access. Your system grants access rights using this key.
- Session authentication. Sessions, via cookies, POST/GET parameters, or otherwise, are initiated, and used for subsequent access to APIs. This requires that clients can store their SESSION (a small number of libraries and platforms require a bit more work to do this). The session may be verified by your site, or by a 3rd party using various mechanisms.
- Per-API authentication. Each API call requires credentials in some form (as POST parameters, HTTP authentication, etc.)
API keys fit the basic problem of controlling who has access to your APIs (including throttling), and can be useful for providing access to both public and private data, though private data requires additional authentication.
Sessions are the most common authentication, often relying on a 3rd party storing and checking the credentials (as Twitter does, or Google, etc.).
Per-API authentication is the least useful, but can be a valid compromise when the clients or server system require it.
As for the debate on REST versus other approaches, it can be heated, but most often centres around:
Is basic HTTP good enough, or does it need more mojo?
A few choice SOAP versus REST links:
And a few pointers on basic API design:
And if you haven't read it, I strongly recommend reading Ryan Tomayko's How I Explained REST to My Wife (it's funny and informative).