RestLess - A Simple REST Framework

Posted on Saturday, April 19, 2008

I have been disappointed with the amount of legwork involved with setting up a simple REST API, so I decided to write a small attribute-based framework. The goal was to make it as simple as possible and be discoverable. Right now, the framework only supports GETting objects from your api, but that will change very soon.

Setting up RestLess

1. Add a reference to RestLess.dll
2. In web.config under <system.web>, add
   <httpModules>
       <add type="RestLess.RestHttpModule, RestLess" name="RestLess" />
   </httpModules>
3. To tell RestLess where your API root directory is, in web.config under the <configuration> section add this key (you can make this whatever path you want)
   <appSettings>
       <add key="RestLess::BaseUrl" value="api/" />
   </appSettings>

That's it!

Exposing an object via the api

You may have a Product object in your application with the properties Name, Description, and Amount. If you want to expose this via the api, you would simply decorate this class as follows. (RestLess code in blue, Comments in green)

    // decorate the class as a RestResource, the first parameter is the url of the
    // resource appended to the root url (defined in web.config). In this case /api/products/
    // the second parameter specifies if this resource is discoverable (more on this later)
    [RestResource("products", true)]
    public class Product : IRestReadable
    {
        private string _name;
        private string _description;
        private double _amount;

        // render this property as xmlelement "productname"
        // IOType.InputOutput specifies that this property will be rendered
        // to the outputted xml, and can also be inputted via querystring
        [RestProperty("productname", IOType.InputOutput)]
        public string Name
        {
            get { return _name; }
            set { _name = value; }
        }

        // render this property as xmlelement "productdescription"
        // IOType.Output specifies this property is rendered to the user,
        // but it is not allowed in querystring for input
        [RestProperty("productdescription", IOType.Output)]
        public string Description
        {
            get { return _description; }
            set { _description = value; }
        }

        // render this property as xmlelement "amount" (output only again)
        [RestProperty("amount", IOType.Output)]
        public double Amount
        {
            get { return _amount; }
            set { _amount = value; }
        }

        #region IRestReadable Members

          public object GetRestObject()
          {
              // this is where you could go access your data access layer or whatever
              // method you choose.
              // this is also where you could request an API key via querystring for security etc
              // since productname is specified inputoutput, you should check for
              // Request.QueryString["productname"] to get any data the user sends

              // for the purposes of this demo, lets just make an object and pass it back
              Product p = new Product();
              p.Name = "Super Fly Ink Pen";
              p.Description = "This is the most super fly ink pen ever";
              p.Amount = 10.00;

              return p;
          }

          #endregion
    }

Done - that's all you have to do! You can add these attributes to as many of your classes as you want to expose through your api.

If you request the url http://yoursite.com/api/products/default.aspx, the output will look like below

Discovering The API

As I mentioned earlier, the second parameter of the RestResource attribute specifies if the resource is discoverable. If this parameter is set to true, you can visit http://yoursite.com/api/discover.aspx to see what the available resources are. The output of http://yoursite.com/api/discover.aspx will look something like below (notice another Customer object - I did not include this class for brevity).

I plan on making lots of updates and changes to the framework as needed (I am VERY open to suggestions!!). This is a rough-rough draft, but seems to work well.

... now go and add an API to your .NET application in a few minutes. :)

** UPDATE **
An updated version has been posted to http://ndepth.net/blog/restless-a-simple-rest-framework-part-2/. This version includes cleaner urls (no default.aspx) and IRestWritable.

Jayme

Comments

• Chris Carter on 4.20.2008 at 8:35 PM

• I'm not sure, of the 10 kicks you received(as of the time of this writing), how many of those who kicked actually played around with your assembly. I took some time cuz I like the concept but I have issues with the mention of the term REST.

  I'm confident that Mr. Fielding would not agree that anything ending with .aspx would fit his vision of REST. The prototype javascript guys, set up their online api using a RESTful architecture. If I want to know about the Element class, this is what I type: http://prototypejs.org/api/element. My expectation is that I'm going to get a web page that describes the prototype Element class. Already know generally what the Element class is used for but got stuck on the down method? type this in http://prototypejs.org/api/element/down. My expectation is to receive an html page(cuz i typed it in my browser) that describes the down method of the element class, and that's exactly what i get.

  The delicious peeps did something similar. Want to know my bookmarks tagged as css? type this in: http://del.icio.us/chrcar01/css. Need to develop some sooper cool app that needs to get a JSON feed of my urls tagged as nhibernate? here ya go, feeds.delicious.com/.../nhibernate

  What's the common thread? I have no clue about the technology that's delivering that content. Maybe it's .NET, or Java, or Python, Apache, IIS, or whatever, I don't know about the implemented architecture and I don't care.

  On the developer side of things, what if you switched from .NET to Ruby on Rails on the server. You're screwed on any content previously published with a URL with an extension like .ASPX. Anyone who's bookmarked that aspx page will prolly get a nice 404, even though the content exists, it just doesn't have that extension.

  RestLess seems more like straight up ASP.NET WebServices plus URL rewriting minus an xsd that can verify whether the response returned from the service matches your expectation. This is NOT a bad thing, not at all, that is, in the right context.

  I'm thinking more of the consumer side of things as I'm writing this. So when I call something rendered through RestLess, and it returns xml, I try to imagine how painful it might be to use the results. Sending back plain jane xml requires me to do xml parsing which sucks, that's time consuming monkey coding. The web service client you get from wsdl.exe outputs one of those for you, no extra code required. Exposing your classes to a web service requires one attribute, Serializable, for .NET to know how to send that to clients requesting your resource.

  So I guess I'm looking more for the need that RestLess fulfills, it's not REST and it's a step backwards from web services. Do you have a scenario where you've used RestLess because web services did not do it for you?

• Jayme on 4.20.2008 at 10:08 PM

• Hi, Chris :) thanks for your comments.

  I agree with you on the url including .aspx, I don't like it either. The only reason I included it is so users didn't have to configure IIS to process all requests through the runtime (eliminate the need for .aspx, .ashx, etc) to map to asp.net. If you configure it as such, problem solved.

  If you want great urls (which we all do), you could easily do yoursite.com/products/productname ... with the help of a urlrewriting engine - which is a problem RestLess is not built to solve.

  With that said, the discover option needs a lot of work. It's hardcoded now to show default.aspx and any parameters the user could pass. It definitely needs to be customizable in the event someone uses a urlrewriting engine to tidy things up.

  The verbs  that  are sent to the URI determine the method that is called (GET = IRESTReadable), soon to come will be IRESTWriteable, etc which will handle other verbs at the specified URI.

  Hope this helps!

  Jayme

• superjason on 4.21.2008 at 8:28 AM

• Possibly a stupid question:

  Can IIS be configured to allow ASP.NET to process files without extensions?

• Karthik on 4.21.2008 at 9:03 AM

• Jayme,

  This is a great concept. You might want to try extending it for ASP.NET MVC so you can easily get rid of the .aspx for the requests :)

  Also the open source MVCContrib project includes a SimpleRest controller to route true REST based requests with.

• Jayme on 4.21.2008 at 10:08 AM

• superjason,

  Yes. It's called an IIS wildcard mapping - check out this link for more info. weblogs.asp.net/.../tip-trick-integ

  Karthik,

  Good idea!.. I haven't messed around with MVC yet as much as I'd like :(

• Ken Robertson on 4.21.2008 at 10:39 AM

• Jayme, looks pretty sweet! One thing I'd be interested to see would be to utilize something like a "RestMethod". Right now, the API modifies the objects directly, but might be good to move towards and intermediary. Usually with REST, they still follow the MVC pattern (view being the xml). Currently, it is kind of just MV... there is no intermediary between the model and the view. For read-only, it isn't as important, but for doing post/puts, you'd want it to do things like permission enforcing, validation, etc.

• Joe on 4.23.2008 at 2:50 PM

• Jayme, very nice work!

  Would you please post the source code for restless.dll, I need that

  I want to see delete, put, update soon.

• Jayme on 4.23.2008 at 10:26 PM

• IRestWritable implemented and cleaner urls.

  ndepth.net/.../restless-a-simp

  Jayme

• Piers on 10.20.2008 at 6:34 PM

• I've put together a series of posts on my blog shouldersofgiants.co.uk/.../blog about using the latest incarnation of MVC to create a RESTful web service using C# and ASP.Net. I wonder if the latest version of MVC would let you do all you need?

• Sebastien Lambla on 11.24.2008 at 1:24 PM

• Clean URIs are completely orthogonal to REST constraints and is not one of them.

• best online slots on 3.04.2009 at 3:36 AM

• Thanks for the update of your journey.I know there are some people here that hate their jobs and aren't in the design field yet. I am working for an online bingo company which is among the biggest dealer in "a href="http://www.thebestonlineslots.com"best online slots</a>. I have a developed few websites projects in hand and wanna hire some professional software developers.

• Terry Walker on 3.25.2009 at 4:55 AM

• Wow, I never knew that A Simple REST Framework. That’s pretty interesting...

• ricky on 5.07.2009 at 1:48 AM

• Interesting post, it helps me in my research, thanks!

• tukang nggame on 6.05.2009 at 5:25 PM

• this is great information that i know a lot of people are interested in, thanks for sharing the code

• steve on 6.15.2009 at 9:21 PM

• good. learn something from these two articles.

• Sulumits Retsambew on 6.22.2009 at 7:14 AM

• hello, this is really what i am looking for, thanks for informing.

• belajar seo para pemula on 7.04.2009 at 12:04 AM

• thanks for your info

• belajar seo para pemula on 7.04.2009 at 12:05 AM

• thanks for info i know a lot of people are interested in, thanks for sharing the idea

• club penguin cheats on 7.05.2009 at 8:51 PM

• I agree with you on the url including .aspx, I don't like it either. The only reason I included it is so users didn't have to configure IIS to process all requests through the runtime eliminate the need for .aspx, .ashx, etc to map to asp.net. If you configure it as such, problem solved.

• Rusli Zainal Sang Visioner on 7.08.2009 at 1:00 PM

• accurate, concise, bold! Are you me. thank you and wish a nice day

• Stop Dreaming Start Action on 7.08.2009 at 1:01 PM

• thanks for your sharing. that useful to fix the same problem

• George Foreman outdoor grill on 7.19.2009 at 11:48 PM

• Pretty useful for the RestLess set-up, but I still gotta check out the code more carefully to understand how to expose an object via api, I still always program with sheer strength.

• Learn how to play street style craps on 7.20.2009 at 4:51 AM

• Not sure for .net but for java jersey(https://jersey.dev.java.net/) is the simplest followed by RESTEasy and RESTLets, for basic stuff Jersey rocks.

• Lida on 7.29.2009 at 6:25 AM

• Good on your

• Seo Web Directory on 8.05.2009 at 10:14 AM

• great idea but iam still dont understand

• Lear on 8.06.2009 at 2:22 AM

• thank you for your codes.

• wisata seo sadau on 8.09.2009 at 8:50 AM

• i like it. thx for the tips..

• rugs on 8.12.2009 at 4:44 PM

• <p><a href="http://www.homedecors.com.au" title=" home decor" target="_blank"> home decor</a> or any community of people indispensable.</p>

  <a href="http://www.leatherlounges.net.au" title="leather lounges" target="_blank">leather lounges</a> or any community of people indispensable.</p>

  <p><a href="http://www.onlineauctions.net.au" title="online auctions" target="_blank">online auctions</a> or any community of people indispensable.</p>

  <p><a href="http://www.kidonlinegames.net/43/Race-Games/Dune-Buggy-Game" title="dune buggy game" target="_blank">dune buggy game</a> or any community of people indispensable.</p>

• home decor on 8.12.2009 at 4:45 PM

• thanks

• leather lounges on 8.12.2009 at 4:46 PM

• very nice

• online auctions on 8.12.2009 at 4:46 PM

• thanks admin

• dune buggy game on 8.12.2009 at 4:47 PM

• goods

• Cell Phone Review on 8.14.2009 at 9:18 AM

• thanks for shared

• News Gadget New on 8.14.2009 at 9:20 AM

• Great job

• Halı Yıkama Makinası on 8.20.2009 at 9:17 AM

• thanks

• Rusli Zainal Sang Visioner on 8.23.2009 at 4:41 AM

• Hi,

  thank for sharing the simple rest framework. Visit Rusli Zainal Sang Visioner

• rusli zainal sang visioner on 8.25.2009 at 1:24 AM

• great site

• Stop Dreaming Start Action on 8.29.2009 at 9:18 AM

• Your post is so great and useful for me, thanks for this great work and informative read

• Lowongan Pekerjaan Terbaru on 8.29.2009 at 9:25 AM

• Your post is so great and useful for me, thanks for this great work and informative read and I need this code

• stop dreaming start action on 9.03.2009 at 10:06 AM

• thank you for useful tutorial. i love it

• RUSLI ZAINAL SANG VISIONER on 9.03.2009 at 10:08 AM

• thank you for your tutorial. That's it great

• العاب تلبيس on 9.08.2009 at 1:08 AM

• #

  thank you for your tutorial. That's it great

• mengembalikan jati diri bangsa on 9.16.2009 at 6:12 PM

• thank for sharing the simple rest framework. stopdreamingstartaction.studikomputer.com/.../kenali-dan-kunj http://gebe.blogdetik.com/kibarkan-bendera-mengembalikan-jati-diri-bangsa/

• Digitals Review on 9.18.2009 at 3:34 AM

• i like it. thx for the tips..

• Travel Guide on 9.18.2009 at 3:36 AM

• great idea but iam still dont understand

• Kenali dan Kunjungi Objek Wisata di Pandeglang on 9.18.2009 at 3:37 AM

• Interesting post, it helps me in my research, thanks!

• cell phone news on 9.18.2009 at 3:40 AM

• thanks admin

• Lowongan Pekerjaan on 9.18.2009 at 3:41 AM

• thank for sharing the simple rest framework

• Kenali Dan Kunjungi Objek Wisata Di Pandeglang on 9.18.2009 at 8:10 AM

• Pretty good post. I just stumbled upon your blog and wanted to say that I have really enjoyed reading your blog posts. Any way I'll be subscribing to your feed and I hope you post again soon.

• Kenali dan Kunjungi Objek Wisata di Pandeglang on 9.19.2009 at 2:07 PM

• thank you for your tutorial. That's it great

• oes tsetnoc on 9.24.2009 at 2:03 PM

• Hello webmaster I like your post so much. Thanks.

• Mencari Blogpreneur Sejati on 9.24.2009 at 2:04 PM

• Wow! Thank you! I always wanted to write in my site something like that. Can I take part of your post to my blog?

• Kenali dan Kunjungi Objek Wisata di Pandeglang on 9.24.2009 at 2:05 PM

• I found your site on del.icio.us today and really liked it .. i bookmarked it and will be back to check it out some more later ..

• freekidsgames on 9.25.2009 at 3:42 PM

• Super simple! Thank you!

• Cell Phone Reviews on 9.27.2009 at 8:33 AM

• Thanks admin ... Excellent!

• Kenali Dan Kunjungi Objek Wisata Di Pandeglang on 9.29.2009 at 10:08 AM

• Nice share here...thanks for share this.

• Serunya Belajar Seo on 9.29.2009 at 10:12 AM

• This is a good post...i really like this..thanks

• top culinary school on 9.30.2009 at 4:01 AM

• Usually, you want to keep your URLs simple, and it is always preferable not having extensions in sub-links for simplicity.

• moratmarit on 10.02.2009 at 8:18 AM

• This is actually really interesting regarding your fact article here, This article is very informative.

• cah baoges on 10.02.2009 at 8:19 AM

• thanks for this usefull informations..

  now i find what i want to know.thanks.

• cah bagoes on 10.02.2009 at 8:25 AM

• thanks for this usefull informations..

  now i find what i want to know.thanks.

• oes tsetnoc on 10.02.2009 at 8:44 AM

• This is actually really interesting regarding your fact article here, This article is very informative.

• Kenali Dan Kunjungi Objek Wisata Di Pandeglang on 10.02.2009 at 2:04 PM

• I havent any word to appreciate this post.....Really i am impressed from this post....the person who create this post it was a great human..thanks for shared this with us.

• Kenali Dan Kunjungi Objek Wisata Di Pandeglang on 10.02.2009 at 2:04 PM

• Have you ever considered adding more videos to your blog posts to keep the readers more entertained? I mean I just read through the entire article of yours and it was quite good but since I'm more of a visual learner,I found that to be more helpful well let me know how it turns out! I love what you guys are always up too. Such clever work and reporting! . This is a great article thanks for sharing this informative information.. I will visit your blog regularly for some latest post.

• online culinary schools on 10.02.2009 at 11:19 PM

• Thanks for the tutorial. Trying to use it on Linux right now >_<

• Kenali Dan Kunjungi Objek Wisata Di Pandeglang on 10.05.2009 at 5:47 AM

• Thans for this tutorial...so usefull to me.

• Kenali Dan Kunjungi Objek Wisata Di Pandeglang on 10.05.2009 at 5:47 AM

• Thans for this tutorial...so usefull to me.

• Kenali dan Kunjungi Objek Wisata di Pandeglang on 10.06.2009 at 6:22 PM

• Nice post, thumb up!

• Kenali dan Kunjungi Objek Wisata di Pandeglang on 10.07.2009 at 1:50 PM

• Good post thanks for shaing

• kenali dan kunjungi objek wisata di pandeglang on 10.07.2009 at 8:45 PM

• I mean I just read through the entire article of yours and it was quite good but since I'm more of a visual learner

• games on 10.09.2009 at 1:52 AM

• Good idea!.. I haven't messed around with MVC yet as much as I'd like :(

• mp3 indir on 10.10.2009 at 8:24 PM

• good jobs

• mp3 indir on 10.10.2009 at 8:24 PM

• Good idea!.. I haven't messed around with MVC yet as much as I'd like :( ver nice blogs

• mp3 indir on 10.10.2009 at 8:26 PM

• very god blogs

• film indir on 10.10.2009 at 8:26 PM

• thanks adminn

• film arsiv on 10.10.2009 at 8:27 PM

• thank you admin

• seo company on 2.08.2010 at 1:42 AM

• It is indeed a great resource to obtain information on this subject. Keep posting. Thanks.

Leave a Comment