.NET Zone is brought to you in partnership with:

Simone Chiaretta is a Software Architect and Developer from Milano, Italy that enjoys sharing via his blog his development experiences and more than decennial knowledge on web development with ASP.NET and other web technologies. He is Microsoft MVP in ASP.NET and he has been involved in many Open Source projects, but now he focuses only on SubText and taking it to the next level. He just wrote a book: Beginning ASP.NET MVC, published by Wrox Simone is a DZone MVB and is not an employee of DZone and has posted 67 posts at DZone. You can read more from them at their website. View Full User Profile

Web API preview 6 is out: how to get a RESTful mind

12.02.2011
| 3031 views |
  • submit to reddit

As you may or may not have heard, yesterday WCF Web API preview 6 has been released.

If you never heard about it I recommend you read the quick introduction on CodePlex, but basically it is a facility that helps you expose your services over the web, taking advantage of the richness of the HTTP protocol, in a RESTful way (vs using SOAP or other abstraction layers).

Getting started resources on Web API

To quickly get started with it you can download the code and samples, and download the compiled CHM for a more conceptual and step by step approach. Alternatively you can get the latest version directly from NuGet.

Still on the project’s documentation page you can find some quick starts covering the basics of how to build a very simple web API, how to add CRUD operations on single resources and a overview of the “API Enhancements”, which is a very convenient set of features to make development easier and more integrated with ASP.NET MVC. Also a quick video intro on the testing UI is available.

Also interesting, if you have one hour and 20 minutes, is the introductory talk Glenn Block presented at TechDays Belgium earlier this year: WCF Web APIs, HTTP your way. At the same venue, Glenn also dove a bit deeper into more advanced features of REST web stack of WCF: Unlocking the secrets of REST with WCF.

Understanding REST

All those docs and links will make you understand how to implement a RESTful API on the .NET stack, but will not explain you which are the principles of a REST api.

Here are a few books and online resources I recommend you have a look at to understand REST and how to properly design API that don’t look just like RPC on a different protocol.

Books

Book also used by Glenn as source of inspiration to design the Web API is “REST in Practice” published by O'Reilly: it covers REST from the enterprise point of view and does so by implementing RestBucks, a coffee ordering REST API. It is implemented in .NET and Java, and you can get the source from the book’s site.

If you prefer a cookbook style approach, RESTful Web Services Cookbook: Solutions for Improving Scalability and Simplicity, still from O'Reilly, explains the solution to many of the problems and questions you might have when designing a REST api.

Finally, as a quick reference and a set of rules if you want to make sure you get the API “semantically right” I liked the REST API Design Rulebook (again from O’Reilly). The author also introduces a supposed standard called Web Resource Modeling Language (WRML) which frankly I’ve never heard of before and looks like it’s a brain-child of the author of the book: just skip that part.

Sample projects and articles

The most useful online resources I found are related to the REST in Practice book.

First is the article How to GET a cup of coffee, which was the original idea on which the book was based.

As I mentioned above, the book comes with a sample built with .NET, but using a custom implementation. Fortunately two folks in the .NET community ported the sample RestBucks project over to WCF Web API:

What is great about restbuckson.net is that not only you get the code to learn from, but if you want you can build your client (or use fiddler) and play with the APIs directly online. And in addition it has great documentation and also a series of blog posts that explain the implementation details.

Now… go GET some REST

Ok… stupid joke…

I’m lately getting into REST services for the new system architecture I’m implementing where I work, and even it might require changing a bit the initial approach (thinking in term of resources for things outside of CRUD is not that easy at first), it makes everything very easy to implement, super interoperable (and having a lot of different systems interoperability was a issue) and makes it straightforward to later push the same API to the outside world.

Hope these resources can get you start looking into REST, you’ll not regret it.

References
Published at DZone with permission of Simone Chiaretta, author and DZone MVB. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)