Notes On RESTful Architecture - I

  • Article

This post is a summary of notes I am taking while reading a book RESTful .NET: Build and Consume RESTful Web Services with .NET 3.5.

Resources and URI’s

  • RESTful services model the interaction with user agents based on resource.
  • The first thing to do is to determine which resources you’re going to expose.
  • A resource is any information that you want to make available to others.
  • Some resources are static…, and some resources are dynamic.
  • Once you’ve identified the resources you’ll map then to URI’s.

URI design

  • All resources are uniquely identified by a URI.
  • The idea behind REST is to design your URIs in a way that makes logical sense based on your resource set (vs. GUIDS or/and funky query strings)
  • When designing the associations between resources and URI’s, it may be useful to map them as if you were designing a browsable website.

Uniform Interface

  • User agents only interact with resources using the prescribed HTTP verbs.
  • The four main verbs are:
    • GET
      • Retrieves a resource.
      • Guaranteed not to cause side-effects (SAFE).
      • Cacheable.
    • POST
      • Creates a new resource.
      • Unsafe, effect of this verb isn’t defined by HTTP.
    • PUT
      • Updates an existing resource.
      • Used for resource creating when client knows URI.
      • Can call N times, same thing will always happen (idempotent).
    • DELETE
      • Removes a resource.
      • Can call N times, same thing will always happen (idempotent).

Checklist for building RESTFul architecture:

  • Decide what your recourses are.
  • Map the resources to URIs.
  • For each URI define it’s media types [HTTP Content-Type]:
    • XML [application/xml, text/xml - deprecated].
    • RSS/Atom [atom more recent, devs like it, APP or AtomPub protocol].
    • XHTML [application/xhtml+xml].
    • JSON [application/json]
    • More at www.microformats.org