I have just published 2 new articles:
Implementing and testing server-driven content negotiation for your REST resources with WebSphere sMash
Scaling WebSphere sMash Web 2.0 applications: Part 1: Overview of WebSphere sMash topologies
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.NO!!! Resources can be anything, from a Business Process to an Image.
RESTful Principals Include:
* Identifiable resources (URIs)http://sports.espn.go.com/oly/summer08/swimming/news/story?id=3530615
* Uniform InterfaceGET, PUT, POST, DELETE
* Stateless CommunicationScalable, loose coupling
* Resource RepresentationsMultiple ways to represent (PDF, HMTL, XML,) - via content typesHTTP has negotiation capabilities (e.g. ACCEPT)
* HypermediaServer provides links to resourcesAllows for evolution
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?
* What are the status codes returned?HTTP defines standard return codes200 = ok301 = moved permanently400 = bad request , 401 = unauthorized , 404 = not found
3.) Categorize Resource types:
Example: * Simple Resource Types (".../
4.) Maintain Mutability of Verbs
* GET / HEAD (No Side Affects)* POST/PUT/DELETE (Assumed Side Affects)* Middleware State (No-no, State Transfer)* Atomic Operations - RESTful Resources should start and end DB Transactions.
5.) Implement Optimistic Concurrency
* Optimistic concurrency via E-Tags, Timestamps
* Check-in/Check-out semantics if stricter policy is needed, but never hold database locks
6.) Define a Consistent Query Syntax in your organization
REST defines no standards on query parameter names. For example, you may choose to provide standard params for filtering, Sorting, and Ranges.
/resource?filter="name startsWith b && age gt 30"
7.) Implement Filtering, Sorting, and Ranges for Data Sets
Even if you start out small, if your data grows, need to provide these.
8.) Linking over Relationships
Prefer Linking over tightly coupled data. Use ATOM as a payload for establishing relationships
9.) But, sometimes I have relationships....
Sometimes you need to do bulk loading of related data. Some Techniques:
* Special parameter/Order?loadRelated=LineItemsVery quickly starts becoming RPC
* Headers and Schemas (Better)Accept: application/eager+atom+xmlAccept: application/atom+xml
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)
b.) Use Header (Cleaner looking)Accept: application/myVer+atom+xml Custom Header
11.) Lock Down your URI's and Implement Instance Based Security
With REST, I can easily secure URI's, but make sure to implement Instance Based security for User sensitive Data. If I log in successfully as /account/roland, I have to protect against /account/mike.
The service provider should make sure to access the identity from the Subject or Context and compare to the URI requested.
12.) READ THE HTTP SPECS and stick to themHTTP HeadersHTTP Response Codes
Do not add semantics to headers that are not meant. Routers and firewalls make use of many headers in strange and curious ways.
13.) Implement Content Negotiation
14.) Sometimes you need to Relax.Use cases emerge that may not fit naturally.
Partial UpdatesBatch Updates
Query params (Be careful, could become RPC Very Fast)
The HTTP Spec is looking at a new verb called PATCH
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?
16.) Write your Unit Tests first using something like HttpUnit.
I demonstrate this here.