RESTful web service development

REST summary

• every resource has to be discoverable via links
  • basically a developer can learn the API with a browser
  • also, with links, you can mingle resources from any REST api
• verbs
  • GET - retrieve a specific resource
  • DELETE - delete a specific resource
  • PUT - update a specific resource
  • POST - create a new resource and return the ID - neither safe nor idempotent
• you can repeat calls to GET/DELETE/PUT all day long if they fail
• to provide complex functions (eg query and result) as resources...
  • create a query resource with a TTL
  • add to it
  • execute it (and auto-release?)
  • release it (or let this happen automatically with server-side TTL cleanup)
• how do we handle huge lists? like this?
  • wya/users
    • returns the first 10 users with a link to next 10
  • wya/users/range/11-20
    • a link to users 11-20
• {resource}/edit should return an edit form (cool) - I think recess already does this?
• authentication - use SSL with HTTP Basic Authentication, or SHA1 signature (ala Amazon S3)

REST Examples

1. The best example I have to follow is the Twitter API. It *obviously* scales. It uses Basic Authentication, which sucks (everything is plaintext, holy shit). BETTER force it to use SSL.
2. The other excellent example is the Amazon S3 API. Authentication is brilliant - it uses a SHA1 signature of the request, which MUST include a timestamp within the last 15 minutes. There is a set of rules for turning the request URL into the request string that is signed.

Signature = Base64( HMAC-SHA1( UTF-8-Encoding-Of( YourSecretAccessKeyID, StringToSign ) ) );