RESTful thoughts - Why ASP .NET MVC?

Let me begin by building the frame of how we approached the idea for a new API before I go into the details of the technologies we chose. We needed an API that would address the following:

1. Secure
2. Follows common community standards / practices
3. Public interface
4. Extremely easy to consume
5. Supported formats (at least) XML, JSON --> optionally to be extended to XHTML, ATOM, etc...
6. Needs to scale and understand complex relationships
7. Needs to scale fast and with agility

The architecture / protocols we chose were - REST(delivery / interaction) + OAUTH(Authentication). I personally feel that this approach is instrumental to the success of your software when you're developing an externally facing API.

Technologies face sweeping changes , patterns / standards change either incrementally or not at all. Fielding did not create REST, he just documented the architectural principles (extremely well). Consider how much simpler it is to develop for a browser when it follows css standards (Firefox, Safari, Opera).

Why REST? The pattern addresses 6(#2-7) of the 7 needs above. Plus, adoption since Fielding's dissertation in 2000, has sky rocketed. Most Web Devs have at least heard of REST and I am pretty sure the majority of the community has knowingly / unknowingly used the pattern.

Patterns are tried and true - that's why they are patterns. Communities of people come together and agree that pattern x or specification y should be a standard. This blog is my opinion, though I would like to think it is "fact."

The real fact is that there are people out there in the tech pot that are far more intelligent than I am, that are writing specifications that my opinions try to enforce - accurately or inaccurately. Remember the I/O tower in Tron? It had 1 purpose -> communication and apparently it did it well, just look at how old that guy was.

That's how I want this API to turn out, not old and crusty, but constantly predictable. Let me and the patterns worry about the consistency of the API while you enjoy the serendipity of consuming it.

Why OAUTH? Look at the majority of web facing, public APIs available to us. Talk about a seriously cool time to be a developer - the days of making an RPC to some arcane server buried at some university are gone. Remember the MCP in Tron? Yes he gobbled up all of the resources and shut down systems, but that's not the point I am trying to make, so we'll ignore that. He acted as the gatekeeper - he was built to be a way to protect and secure stuff, to check and authorize credentials. OAUTH is a lot like that and it is a proven pattern with implementation libraries to boot!

Consumers of my API will not have to wait for me to produce documentation and sample code libraries for some custom authentication implementation I tossed together - they can just head over to oauth.net. OAUTH is an open protocol that has been tested, is proven, and is simple to implement - #1 answered, as well as supporting #2 and #4.

For an API, you don't want to have to introduce anything synonymous to the holly hack or your typical web app "browser test" --> that road will take you to an API that collects dust and not consumers. So, first thing first - standards over technology

Once we selected the standards we started targeting some web frameworks for considerations. Here are some of the technologies that we considered:

Ruby + Framework (Rails, Merb, etc...)
While Rails or Merb we're solid contenders. Rails specifically, I enjoy the opinionated approach, the scaffolding that comes right out of the box, and the DRY that it embraces. I built the 2nd version of the API using Rails but later bailed because implementation would be more difficult considering our existing domain and established environments. If we ever did want to come back around and use Rails or something like it we could do so without impacting the consumers - remember pattern / standards over technology.

The good:

• Opinionated
• Testability
• Elegant, simplistic
• RESTful patterns built in

The bad:

• No established local or prod environments to support the code,
• Existing domain is .net, existing domain / data model is not opinionated - so we would either modify Rails or our model which would exceed our time line to implementation.

ADO.NET Data Services / WCF + RESTful Toolkit I'll be honest, when I saw Astoria come up on the Microsoft pipe I immediately thought SOAP web services. Was that the right thing to do? No. Did it skew my perception of ADO.NET data services? Yes. So far, regarding some patterns, Microsoft has taken x and added .NET to it. This is OK, in fact it's inevitable - you embrace patterns and are passionate about your technology some of your principles and opinions will become integrated into the pattern. Unfortunately sometimes those opinions cross lines which make it difficult for developers to implement the technology. XML web services as Microsoft SOAP web services, REST as WCF / ADO .NET services.

Last Tron analogy, I promise. Let's talk about Sark? The guy was an overbearing heavy hitter. He wasn't like Tron. Tron played games, that's all he did and he did it extremely well.

End result: he beat the guy who tried to do everything.

The fact is that no piece of software or framework will be everything to everyone - so don't try to make it that. Why does Microsoft have 2 technologies that attempt to do the same thing 2 different ways?

So why not use WCF or ADO .NET WS for a RESTful API? I answered that question with a question: What is it that I am trying to develop?

I simply need a RESTful web application, bottom line.

WCF + RESTful Toolkit
The good:

• It does everything I need and lots more
• It can be web based
• Has a super-cool feature for documentation

The bad:

• It does lots more - too much in fact
• It is highly complex
• It was originally based on SOAP and WS-*
• URIs are difficult to control / manipulate
• HTTP modules are necessary to have extensionless URLs (I am definitely not a fan of .svc)
• According to Flanders' new book RESTful .NET WCF "...actually did have support for building services using REST, but the WCF programming model lacked explicit support for doing so."

WCF, to me, feels like communication between systems was a priority and communication via Hypermedia based systems "RESTfully" is kinda like an add on. I need more focus and less technology getting in my way. I wrote the 1st prototype of the API using WCF, but trashed it because of complexity and overhead.

ADO.NET Data Services

The good:

• Web based
• Microsoft apparently started from scratch on this one - not a Web Services carry over - according to Pablo Castro's Mix08 presentation
• Supports ATOM, json, XML content by default
• Some cool mechanisms for querying
• Wicked easy to extend and develop for / against

The bad:

• Architecture (Data provider and DataSets) - DataSets have historically been bloated. I cannot help but think that there was some sort of pattern carry over from the old Web Services
• I personally do not like the URIs - http://api/service.svc/Users(1)/Bookmarks
• The service as a whole feels "REST-like" and not RESTful
• Things like "$parm", "Expand", etc... tell me that they are trying to be everything to everyone - They cannot use normal request parms because they are tied to LINQ
• URIs are difficult to control / manipulate
• HTTP modules are necessary to have extensionless URLs (I am definitely not a fan of .svc)

I used ADO .NET web services back in the Astoria days, I liked it, I thought it had some really cool features. The technology, however, does not meet my expectations or my RESTful needs

ASP .NET MVC (Beta)

The good:

• Simply, a web application
• I love the MVC pattern
• Easy to develop for
• Easy to consume
• Routes can easily be configured to impose "pure" REST architecture principles - no "REST-like", it is all HTTP - no need for some services framework to lay on top of it and "interpret" requests, low overhead
• No complexities of a service framework
• You can extent request and response formats easily
• Most of all - implementing RESTful architecture is simple because ASP .NET MVC at its root is a web based, hypermedia application framework

The bad:

• You have to enforce RESTful principles (unlike Rails) - MVCContrib helps,
• No default documentation or documenting feature (WCF RESTful toolkit has a very nice documentation feature built in)

As I stated above, simple and focused can get you really far down the road. We talked to a lot of people, and did a lot of research, however, most of the above is my opinion. After using APIs that claimed to be RESTful across the web, I realized that the most important thing for this effort would be to stick to simplicity and go pure REST -> ASP .NET MVC fit our needs and wants to get that done.