But I have been spending a lot of time helping some of my customers with REST Architecture. I figured I would post some here. I will give some bullet points and will be publishing papers soon. Note, these are not in any order of importance. All are important. Note, I am just putting pointers in rough format here, and I will publish some more articles on the topics later.

1.) Understand REST. Here are the top 2 misconceptions about REST:

a.) REST is just any XML over HTTP not using SOAP? NO !!! REST is a Pattern of exchanging Resources. RPC is Not REST

b.) REST is only useful for CRUD(Create, Read,Update, and Delete) semantics.

2.) Define a strategy for defining resource/services:

* What are the resource identifiers?* Is there a hierarchy of resources?E.g. a list of employees may be one resource, each employee is another /employees vs. /employee/empid1* What HTTP Request/Response Headers SupportedAccept, Content-Type, Range, etc….What is the representation of the data exchanged?JSON? XML? PDF?

* What are the methods supported at each resource?Do you support POST, GET, PUT, DELETE?

10.) Think about API Versioning from the start:

* Follow a Close Spec (slow moving)/Open Extension (Popular Extensions become the next wave of standards) Closed/Open* How do I represent Versions? a.) Use URI? /v/3/myResource (better for Bookmarking, expressive)

14.) Sometimes you need to Relax.

15.)Documentation As a Service.

Atom can be a great way to document since you can link to the service URI Patterns.

What should REST Documentation have?

Documentation as a Service/resource/formatsCatalog, Registry What are my URI PatternsWhat Headers do I support?What Verbs are valid for my resource?What Response codes do I support?What do they mean for my service?What formats do I support? (JSON, and ATOM)Which header do I use? Accept, query param?What schema describe it?