restbucks Wiki Rss Feed

Updated Wiki: RestBucks on .Net; the barista-bot

jfromaniello — Wed, 15 Jun 2011 18:16:34 GMT

Previous posts

Imagine now that you have another system running in parallel with RestBucks on .Net using the same object domain. This other system is used by the Barista;

A barista (from the Italian for "bartender") is a person, usually a coffee-house employee, who prepares and serves espresso-based coffee drinks.

What I did in RestBucks was to simulate this behavior; our BaristaBot will pick paid orders each 45 seconds and prepare it. For this purpose I have used some ReactiveExtensions magic:

public class Barista
{
    private readonly ISessionFactory sessionFactory;
    private readonly IDisposable subscription;

    public Barista(ISessionFactory sessionFactory)
    {
        this.sessionFactory = sessionFactory;
        subscription = Observable.Interval(TimeSpan.FromSeconds(45))
            .Subscribe(PrepareNextOrder);
    }

    public void PrepareNextOrder(long i)
    {
        using(var session = sessionFactory.OpenSession())
        using(var tx = session.BeginTransaction())
        {
            var order = session.Query<Order>()
                            .Where(o => o.Status == OrderStatus.Paid)
                            .OrderBy(o => o.Payment.DateTime)
                            .FirstOrDefault();
            if (order == null) return;
            
            order.Finish();
            
            tx.Commit();
        }
    }

    public void Dispose()
    {
        subscription.Dispose();
    }
}

I didn't use the repository or other abstractions here to keep things simples. This solution depends on NHibernate and Rx.

You can test the behavior in our live instance at http://restbuckson.net.

Updated Wiki: Documentation

jfromaniello — Wed, 15 Jun 2011 17:23:26 GMT

Updated Wiki: Documentation

jfromaniello — Wed, 15 Jun 2011 17:22:45 GMT

Updated Wiki: RestBucks on .Net; canceling an order

jfromaniello — Wed, 15 Jun 2011 12:33:38 GMT

Previous posts

In this post we are going to implement a new use case; the customer cancels an order.

Before we go to the REST operation itself it is important to introduce some modifications to our domain class:

public class Order : Entity
{
    //more properties and methods....
    
    public OrderStatus Status { get; private set; }
    public string CancelReason { get; private set; }

    public virtual void Cancel(string cancelReason)
    {
        if(Status != OrderStatus.Unpaid)
        {
            throw new InvalidOrderOperationException(string.Format("The order can not be canceled because it is {0}.",
                Status.ToString().ToLower()));
        }
        CancelReason = cancelReason;
        Status = OrderStatus.Canceled;
    }
}

The method is simple, before changing the state of the order to Canceled we have to validate if the order is at the Unpaid state (remember this graph?), once the order has been Paid or it is at any other stage of the process; the Cancel method will throw an exception.

I’ve tested the happy path as follows:

[TestFixture]
public class GivenAnUnpaidOrder
{
    private Order order;

    [SetUp]
    public void SetUp()
    {
        order = new Order();
    }

    [Test]
    public void CancelShouldWork()
    {
        order.Cancel("error");
        order.Status.Should().Be.EqualTo(OrderStatus.Canceled);
    }
}

And then the not so happy path:

[TestFixture]
public class GivenAPayedOrder
{
    private Order order;

    [SetUp]
    public void SetUp()
    {
        order = new Order();
        order.Pay("123", "jose");
    }

    [Test]
    public void CancelShouldThrow()
    {
        order.Executing(o => o.Cancel("error"))
            .Throws<InvalidOrderOperationException>()
            .And
            .Exception.Message.Should().Be.EqualTo("The order can not be canceled because it is paid.");
    }
}

I choose to use different classes much like as per-context fixtures, because I needed to test several other things when the order is Unpaid/Paid.

The next thing is to handle the REST stuff in the handler:

[WebInvoke(UriTemplate = "{orderId}", Method = "DELETE")]
public HttpResponseMessage Cancel(int orderId)
{
    var order = orderRepository.GetById(orderId);
    if(order == null) return Responses.NotFound();
    order.Cancel("canceled from the rest interface");
    return Responses.NoContent();
}

This handler validate first if the order exists, if it doesn't exists; return 404. If the order exists it calls the Cancel operation and returns 204. You can see the tests here.

Since we are doing something like "soft deletes" the next question is what will happen if somebody makes a GET requests to order/id with the id of a canceled order. In my mind the above Cancel method moves the resource from one collection to another one (the trash) so we can modify our GET to work as follows:

[Test]
public void ACallToGet_ShouldReturnMovedPermanentlyAndNewLocation()
{
    var order = new Order { Id = 123 };
    var handler = new OrderResourceHandler(new RepositoryStub<Order>(order), resourceLinker);
    handler.Cancel(123);

    
    var responseToGet = handler.Get(123, null);

    var expected = "http://restbuckson.net/trash/order/123";
    responseToGet.Satisfy(r => r.StatusCode == HttpStatusCode.MovedPermanently
                            && r.Headers.Location.ToString() == expected);
}

The implementation:

[Test]
public void ACallToGet_ShouldReturnMovedPermanentlyAndNewLocation()
{
    var order = new Order { Id = 123 };
    var handler = new OrderResourceHandler(new RepositoryStub<Order>(order), resourceLinker);
    handler.Cancel(123);

    
    var responseToGet = handler.Get(123, null);

    var expected = "http://restbuckson.net/trash/order/123";
    responseToGet.Satisfy(r => r.StatusCode == HttpStatusCode.MovedPermanently
                            && r.Headers.Location.ToString() == expected);
}

And finally we need a TrashHandler (nice name!):

[ServiceContract, WithUriPrefix("trash")]
public class TrashHandler
{
    private readonly IRepository<Order> orderRepository;

    public TrashHandler(IRepository<Order> orderRepository)
    {
        this.orderRepository = orderRepository;
    }
    
    [WebGet(UriTemplate = "/order/{orderId}")]
    public HttpResponseMessage GetCanceled(int orderId)
    {
        var order = orderRepository.Retrieve(o => o.Id == orderId && o.Status == OrderStatus.Canceled)
                                   .FirstOrDefault();

        return order == null ? Responses.NotFound()
            : new HttpResponseMessage<OrderRepresentation>(OrderRepresentationMapper.Map(order));
    }
}

This is all for now! I will talk about the Pay operation in my next article, thanks for reading!

Updated Wiki: RestBucks on .Net; paying the order

jfromaniello — Wed, 15 Jun 2011 12:31:53 GMT

Previous posts

This time I am going to show how did I implement the use case for payment.

As I shown in my previous post about canceling the order, the first thing to modify is our domain class Order;

public class Order
{
    //more properties and methods


    public virtual Payment     Payment { get; private set; }
    public virtual OrderStatus Status  { get; private set; }

    public virtual void Pay(string cardNumber, string cardOwner)
    {
        if (Status != OrderStatus.Unpaid)
        {
            string message = string.Format("The order can not be paid because it is {0}.",
                                           Status.ToString().ToLower());
            throw new InvalidOrderOperationException(message);
        }
        Status = OrderStatus.Paid;
        Payment = new Payment
                  {
                      CardOwner = cardOwner, 
                      CreditCardNumber = cardNumber
                  };
    }
}

And the next step is to add another operation to our REST end point:

[WebInvoke(UriTemplate = "{orderId}/payment", Method = "POST")]
public HttpResponseMessage Pay(int orderId, PaymentRepresentation paymentArgs)
{
    var order = orderRepository.GetById(orderId);
    if (order == null) return Responses.NotFound();
    order.Pay(paymentArgs.CardNumber, paymentArgs.CardOwner);
    return Responses.Ok();
}

It is a POST to http://restbuckson.net/order/{id}/payment. As usual you can see the tests here.

After you paid an order the order will remain in the “Paid” status for few minutes until the barista prepares it. In my next post I will show how I wrote my barista-bot ;).

Updated Wiki: Documentation

jfromaniello — Thu, 09 Jun 2011 17:44:42 GMT

Overview
Preparing the environment
Running the Application
Implementation:
1. Ordering Coffee
2. Querying the order

Updated Wiki: RestBucks on .Net; querying the order

jfromaniello — Thu, 09 Jun 2011 17:42:44 GMT

Previous posts

In my previous post; ordering coffee we end up with a response from the server with the Location of the new resource.

Then, a REST client is supposed to do a GET of this URL in order to:

Get some additional information, like the total cost of the order which is calculated in the backend.
Get the current state of the order.
Get the links for the next actions.

This must sound familiar if you’ve ever shop online. Even if we don’t have a graphical interface; the workflow is just like any online purchase.

In RESTBucks the order process follows this workflow:

Then, if we do a GET of http://restbuckson.net/order/{id} we will expect something like this:

<order>
    <links>
        <link uri="http://restbuckson.net/order/557056" 
            rel="http://restbuckson.net/docs/order-get.htm" 
            mediaType="application/vnd.restbucks+xml"/>

        <link uri="http://restbuckson.net/order/557056" 
            rel="http://restbuckson.net/docs/order-update.htm" 
            mediaType="application/vnd.restbucks+xml"/>

        <link uri="http://restbuckson.net/order/557056" 
            rel="http://restbuckson.net/docs/order-cancel.htm" 
            mediaType="application/vnd.restbucks+xml"/>

        <link uri="http://restbuckson.net/order/557056/payment" 
            rel="http://restbuckson.net/docs/order-pay.htm" 
            mediaType="application/vnd.restbucks+xml"/>
    </links>
    <location>inShop</location>
    <cost>7.60000</cost>
    <items>
        <item>
            <name>Latte</name>
            <quantity>1</quantity>
            <milk>skim</milk>
            <size>large</size>
        </item>
    </items>
    <status>unpaid</status>
</order>

This is documented here ;) . The purpose of the <links /> section is that the consumer of this API should not know much about the implementation or the location of each step. You can think this as if you were buying something in amazon, you don’t know where is the payment step and it is unlikely that some user will put an URL in the browser like “http://amazon.com/pay”.

Implementing the GET method

The implementation of the get method is this:

[WebGet(UriTemplate = "{orderId}")]
public HttpResponseMessage Get(int orderId)
{
    var order = orderRepository.GetById(orderId);

    if (order == null) return Responses.NotFound();
    
    var representation = OrderRepresentationMapper.Map(order);
    var response = new HttpResponseMessage<OrderRepresentation>(representation);
    
    return response;
}

As I said in my previous post, I am using a OrderRepresentation to -represent- the resource and serialize it.

The OrderRepresentationMapper.Map method converts an Order to an OrderRepresentation as follows:

public static class OrderRepresentationMapper
{
    public static OrderRepresentation Map(Order order)
    {
        return new OrderRepresentation
                   {
                       Cost = order.Total,
                       Status = order.Status,
                       Location = order.Location,
                       Items = order.Items.Select(i => new OrderItemRepresentation
                                    {
                                        Name = i.Product.Name,
                                        Preferences = i.Preferences.ToDictionary(p => p.Key, p => p.Value),
                                        Quantity = i.Quantity
                                    }).ToList(),
                       Links = GetLinks(order).ToList()   
                   };
        
    }

    public static IEnumerable<Link> GetLinks(Order order)
    {
        var baseUri = new UriSegment(ConfigurationManager.AppSettings["baseUri"]);
        var linker = new ResourceLinker(baseUri.Segment);

        var get = new Link(linker.GetUri<OrderResourceHandler>(r => r.Get(0, null), new { orderId = order.Id }), 
                            baseUri + "docs/order-get.htm", 
                            MediaTypes.Default);

        var update = new Link(linker.GetUri<OrderResourceHandler>(r => r.Update(0, null), new { orderId = order.Id }),
                            baseUri + "docs/order-update.htm",
                            MediaTypes.Default);

        var cancel = new Link(linker.GetUri<OrderResourceHandler>(r => r.Cancel(0), new { orderId = order.Id }),
                            baseUri + "docs/order-cancel.htm",
                            MediaTypes.Default);

        var pay = new Link(linker.GetUri<OrderResourceHandler>(r => r.Pay(0, null), new { orderId = order.Id }),
                            baseUri + "docs/order-pay.htm",
                            MediaTypes.Default);

        var receipt = new Link(linker.GetUri<OrderResourceHandler>(r => r.Receipt(0), new { orderId = order.Id }),
                            baseUri + "docs/receipt-coffee.htm",
                            MediaTypes.Default);

        switch (order.Status)
        {
            case OrderStatus.Unpaid:
                yield return get;
                yield return update;
                yield return cancel;
                yield return pay;
                break;
            case OrderStatus.Paid:
            case OrderStatus.Delivered:
                yield return get;
                break;
            case OrderStatus.Ready:
                yield return receipt;
                break;
            case OrderStatus.Canceled:
                yield break;
            default:
                yield break;
        }
    }
}

The GetLinks method builds an enumeration of the possible next steps given the status of an order. The ResourceLinker is just a fancy way to get a link to another action/resource (we didn't implement those actions yet).

If you want to explore how this work (or how to test it) you can have a look to these tests.

In the next article I am going to show how I did the Cancel operation, stay tuned!

Updated Wiki: Home

jfromaniello — Mon, 06 Jun 2011 20:20:10 GMT

This a REST application inspired in the excellent example of the book Rest in Practice.

I started this application as an exploratory example of REST and the state of the art of the web frameworks in .Net.

This is the result of a collaborative work. Even if I wrote almost all the code; I did it with the guidance of the amazing group of experts working at Tellago.

The example has served me to learn the REST theory as well as the new Wcf Web API. It has also served to the team to discuss various different approaches and to explore different technologies.

The purpose of the example is not to show “the” way of doing things but to have something where we can clone, change, discuss and so. Consider this only as one way of doing REST on the .Net platform.

My plan is to keep growing this example as well as write an entire series of posts about how I implemented each use case.

Try online!

Do you want to try the application online without installing anything? http://restbuckson.net

Updated Wiki: Home

jfromaniello — Sat, 04 Jun 2011 14:28:03 GMT

This a REST application inspired in the excellent example of the book Rest in Practice.

I started this application as an exploratory example of REST and the state of the art of the web frameworks in .Net.

This is the result of a collaborative work. Even if I wrote almost all the code; I did it with the guidance of the amazing group of experts working at Tellago.

The example has served me to learn the REST theory as well as the new Wcf Web API. It has also served to the team to discuss various different approaches and to explore different technologies.

My plan is to keep growing this example as well as write an entire series of posts about how I implemented each use case.

Try online!

Do you want to try the application online without installing anything? http://restbuckson.net

Updated Wiki: Home

jfromaniello — Sat, 04 Jun 2011 14:27:01 GMT

This a REST application inspired in the excellent example of the book Rest in Practice.

I started this application as an exploratory example of REST and the state of the art of the web frameworks in .Net.

This is the result of a collaborative work. Even if I wrote almost all the code; I did it with the guidance of the amazing group of experts working at Tellago.

The example has served me to learn the REST theory as well as the new Wcf Web API. It has also served to the team to discuss various different approaches and to explore different technologies.

My plan is to keep growing this example as well as write an entire series of posts about how I implemented each use case.

Do you want to try the application online without installing anything? http://restbuckson.net

Updated Wiki: Overview

jfromaniello — Wed, 01 Jun 2011 17:50:34 GMT

In this post I will give a brief overview of RestBucks on Net.

Briefly RestBucks is a coffee shop as any other, well not as any other. They offer a tasty coffee and what is most interesting for us; a RESTfull interface where the customers can order the tasty black liquid. With this REST interface customers can make an order, customize, cancel, ask if it is ready, and so on. If you want to read a more (but not the whole book) you can read this article in infoq (I strongly recommend you the book though).

Use cases

These are the use cases implemented so far:

The customer makes an order
The customer changes an order
The customer pays the order
The customer queries his order
The customer cancels his order

As well, as:

The barista prepare an order

Implementation details

Since I started to participate in the opensource world with examples, I always tried to avoid examples that doesn’t work in real life or to answer to a poignant question with “it is just an example”. My goal with this application is that you can take it and use it for a real world scenario. Thus I am using real world technology, patterns and methodologies:

A relational database to persist the data.
An Inversion of control container
An Object to relational mapper
Test Driven Development.
As well as other well known patterns that we will discuss in upcoming articles.

The tools I have used for this example were not randomly chosen. They are ready to be used in real world applications.

Updated Wiki: RestBucks on .Net: Ordering Coffee

jfromaniello — Wed, 01 Jun 2011 16:20:31 GMT

Welcome to the second part of the RestBucks on .Net series. Today, I am going to take the first use case of the example: “Ordering Coffee”.

What we know?

We know (is on the book) that the customer will POST (http verb) an xml payload as follows:

This is what we call in REST a REPRESENTATION. It is not the resource itself but just a representation of it.

I have intentionally highlighted three different areas:

(green) Location: this indicate whether the order will be consumed onsite or not. It only accept two different values; “takeAway” or “inShop”.
(yellow) Product name: this is the name of the product.
(red) Product preferences: each product accept different preferences.

I took this one step further from the book and we are going to suppose that at any moment of time, the coffee shop can change their menu and/or the possible preferences for a product.

Also notice that an order might have many items.

The order will be POSTed to an URI like “http://restbucks.com/orders”.

In plural; in rest you create things on collections (plural). To GET/PUT/DELETE an order you generally do something like “http://restbucks.com/order/id” (singular)

The domain

From the little piece of information on the above section, we can trace some core concepts:

Entity	Attributes
Product	Name, Possible preferences
Order	Location, Lines
Order line	Product, Preferences, Quantity

And then we can build an object-oriented :) domain model:

This is a pretty anemic domain model and it doesn’t have all the properties and methods that the current version on codeplex has. But it serve to us for the purpose of our specs so far.

Persistence

For this example I have chosen to use a relational database thru an ORM. I have used the last version of the more mature ORM in .Net; NHibernate. For mapping the domain I have used only conventions with few particular exceptions.

The first thing I did is to write some persistence tests; like this one:

[Test]
public void CanStoreACustomization()
{
    long customizationId;
    using (var session = sessionFactory.OpenSession())
    using(var tx = session.BeginTransaction())
    {
        var repository = new Repository<Customization>(session);
        var customization = new Customization { Name = "Milk", PossibleValues = { "skim", "semi", "whole" } };
        repository.MakePersistent(customization);
        customizationId = customization.Id;
        tx.Commit();
    }
    using (var session = sessionFactory.OpenSession())
    {
        var repository = new Repository<Customization>(session);
        var customization = repository.GetById(customizationId);
        customization.Satisfy(c => c.Name == "Milk" && c.PossibleValues.SetEquals(new[] { "skim", "semi", "whole" }));
    }
}

This kind of tests check that the properties are properly persisted, and for instance that inserting a customization automatically inserts the PossibleValues collection.

Each test destroy and recreate the whole database schema (we use a separated database for testing purposes as explained here).

It is not my plan to post all the tests I wrote, you can have a look to these two class here. The result of these tests is the Customize method in this tiny class. The other method (Generate) define only few general purpose conventions.

The representation

Now, that we have our Order class you might wonder how and where to de-serialize the chunk of xml we see at the beginning.

This broadly discussed but at some point there is some level of agreement; Entities are not DTO (and representations are more or less like DTOs).

We have different ways to de-serialize the representation. For this example I chose to write a typed class and use the standard .net xml serialization (another way might be to de-serialize into a dynamic ExpandoObject).

As you can see, this is quite different to our domain entity and in the long run the difference will be bigger because Representations doesn’t have methods.

After I wrote those classes with their properties; the tests that we have to fix is this one:

[Test]
public void CanDeserialize()
{
    var xml =
        @"<?xml version=""1.0""?>
<order xmlns:xsd=""http://www.w3.org/2001/XMLSchema"" xmlns:xsi=""http://www.w3.org/2001/XMLSchema-instance"" xmlns=""http://restbucks.com"">
  <location>inShop</location>
  <cost>100.4</cost>
  <items>
    <item>
      <name>latte</name>
      <quantity>0</quantity>
      <size>large</size>
      <milk>skim</milk>
    </item>
  </items>
</order>";
    var representation = XmlUtil.FromXmlString<OrderRepresentation>(xml);
    representation.Satisfy(r =>
                           r.Items.Any(i => i.Name == "latte"
                                            && i.Preferences.Any(p => p.Key == "size")
                                            && i.Preferences.Any(p => p.Key == "milk")));
}

To pass this test we need a bunch of attributes and implementing the IXmlSerializable interface for the preferences dictionary.
I am not going to paste here the full implementation of those two classes but you can explore here and here.

The resource handler

This is the way I like to call the class that has the [ServiceContract] attribute in the current bits of the wcf WebApi. It is not the resource it self, for me the resource is the Order class (the domain object) and I don’t like the name of “service” in REST.

The main purpose of the resource handler is to expose an Http interface to our application. In order to do this the resource handler can take dependencies on different services that our internal API expose; e.g. a repository.

To make things clear, there is specific logic that belongs to our domain model; e.g. customer can’t pay an order that he has previously canceled. On the other hand there is specific logic that belongs to the handler; e.g. returns a 404-Not found response when the customer does a request for an order that doesn’t exist in our repository.

This test validate that if the customer does a POST of a product that doesn't exist, then the resource handler must return 400 and a meaningful ReasonPhrase:

[Test]
public void WhenAProductDoesNotExist_ThenReturn400AndTheProperREasonPhrase()
{
    var resourceHandler = CreateResourceHandler();
    var orderRepresentation = new OrderRepresentation
    {
        Items = { new OrderItemRepresentation { Name = "beer" } }
    };

    var result = resourceHandler.Create(orderRepresentation);

    result.Satisfy(rm => rm.StatusCode == HttpStatusCode.BadRequest
                      && rm.ReasonPhrase == "We don't offer beer");
}

This test does another validation:

[Test]
public void WhenItemHasQuantity0_ThenReturn400AndTheProperREasonPhrase()
{
    var resourceHandler = CreateResourceHandler();
    var orderRepresentation = new OrderRepresentation
    {
        Items = { new OrderItemRepresentation { Name = "latte", Quantity = 0 } }
    };

    var response = resourceHandler.Create(orderRepresentation);

    //NOTE: I am not sure if the proper response is NotFound or BadRequest. It is not clear in the book.
    response.Satisfy(rm => rm.StatusCode == HttpStatusCode.BadRequest
                        && rm.Content.ToStringContent() == "Item 0: Quantity should be greater than 0.");
}

and so forth. When the order is ok:

[Test]
public void WhenOrderIsOk_ThenInsertANewOrderWithTheProductsAndPrice()
{
    var orderRepository = new RepositoryStub<Order>();
    var handler = CreateResourceHandler(orderRepository);
    var orderRepresentation = new OrderRepresentation { Items = { new OrderItemRepresentation { Name = "latte", Quantity = 1 } } };

    //act
    handler.Create(orderRepresentation);

    var order = orderRepository.RetrieveAll().First();
    order.Satisfy(o => o.Items.Any(i => i.Product == latte && i.UnitPrice == 2.5m && i.Quantity == 1));
}

[Test]
public void WhenOrderIsOk_ThenInsertANewOrderWithTheDateTime()
{
    var orderRepository = new RepositoryStub<Order>();
    var handler = CreateResourceHandler(orderRepository);
    var orderRepresentation = new OrderRepresentation { Items = { new OrderItemRepresentation { Name = "latte", Quantity = 1 } } };

    //act
    handler.Create(orderRepresentation);

    var order = orderRepository.RetrieveAll().First();
    order.Date.Should().Be.EqualTo(DateTime.Today);
}

[Test]
public void WhenOrderIsOk_ThenInsertANewOrderWithTheLocationInfo()
{
    var orderRepository = new RepositoryStub<Order>();
    var handler = CreateResourceHandler(orderRepository);
    var orderRepresentation = new OrderRepresentation 
                                    { 
                                        Location = Location.InShop, 
                                        Items = { new OrderItemRepresentation { Name = "latte", Quantity = 1 } } 
                                    };

    //act
    handler.Create(orderRepresentation);

    var order = orderRepository.RetrieveAll().First();
    order.Location.Should().Be.EqualTo(Location.InShop);
}

The above tests specify that an order must be saved properly. As you can notice here our resource handler depends on a IRepository<T> and in those tests we are using RepositoryStub<T> which is an implementation of IRepository<T> with a simple in-memory collection.

The last test for this use case is very interesting:

[Test]
public void WhenOrderIsOk_ThenResponseHasStatus201AndLocation()
{
    var orderRepository = new Mock<IRepository<Order>>();
    orderRepository.Setup(or => or.MakePersistent(It.IsAny<Order[]>()))
                   .Callback<Order[]>(o => o.First().Id = 123);

    var handler = CreateResourceHandler(orderRepository.Object);

    //act
    var result = handler.Create(new OrderRepresentation { Items = { new OrderItemRepresentation { Name = "latte", Quantity = 1 }}});

    var expectedUriToTheNewOrder =
        resourceLinker.GetUri<OrderResourceHandler>(or => or.Get(0, null), new { orderId = "123" });

    result.Satisfy(r => r.StatusCode == HttpStatusCode.Created
                                  && r.Headers.Location.ToString() == expectedUriToTheNewOrder);
}

It means that after creating the order, the response status must be Created (201), and there must be a Location header.

The protocol is very clear on this (section 14.40):

The Location response-header field is used to redirect the recipient to a location other than the Request-URI for completion of the request or identification of a new resource. For 201 (Created) responses, the Location is that of the new resource which was created by the request. For 3xx responses, the location SHOULD indicate the server's preferred URI for automatic redirection to the resource. The field value consists of a single absolute URI.

A client application can pull the representation from the header location and get more details of the resource it just created, but that is for my next post :).

Updated Wiki: Documentation

jfromaniello — Wed, 01 Jun 2011 16:19:57 GMT

Updated Wiki: RestBucks on .Net: Ordering Coffee

jfromaniello — Wed, 01 Jun 2011 16:18:14 GMT

Welcome to the second part of the RestBucks on .Net series. Today, I am going to take the first use case of the example: “Ordering Coffee”.

What we know?

We know (is on the book) that the customer will POST (http verb) an xml payload as follows:

This is what we call in REST a REPRESENTATION. It is not the resource itself but just a representation of it.

I have intentionally highlighted three different areas:

(green) Location: this indicate whether the order will be consumed onsite or not. It only accept two different values; “takeAway” or “inShop”.
(yellow) Product name: this is the name of the product.
(red) Product preferences: each product accept different preferences.

I took this one step further from the book and we are going to suppose that at any moment of time, the coffee shop can change their menu and/or the possible preferences for a product.

Also notice that an order might have many items.

The order will be POSTed to an URI like “http://restbucks.com/orders”.

In plural; in rest you create things on collections (plural). To GET/PUT/DELETE an order you generally do something like “http://restbucks.com/order/id” (singular)

The domain

From the little piece of information on the above section, we can trace some core concepts:

Entity	Attributes
Product	Name, Possible preferences
Order	Location, Lines
Order line	Product, Preferences, Quantity

And then we can build an object-oriented :) domain model:

This is a pretty anemic domain model and it doesn’t have all the properties and methods that the current version on codeplex has. But it serve to us for the purpose of our specs so far.

Persistence

The first thing I did is to write some persistence tests; like this one:

[Test]
public void CanStoreACustomization()
{
    long customizationId;
    using (var session = sessionFactory.OpenSession())
    using(var tx = session.BeginTransaction())
    {
        var repository = new Repository<Customization>(session);
        var customization = new Customization { Name = "Milk", PossibleValues = { "skim", "semi", "whole" } };
        repository.MakePersistent(customization);
        customizationId = customization.Id;
        tx.Commit();
    }
    using (var session = sessionFactory.OpenSession())
    {
        var repository = new Repository<Customization>(session);
        var customization = repository.GetById(customizationId);
        customization.Satisfy(c => c.Name == "Milk" && c.PossibleValues.SetEquals(new[] { "skim", "semi", "whole" }));
    }
}

This kind of tests check that the properties are properly persisted, and for instance that inserting a customization automatically inserts the PossibleValues collection.

Each test destroy and recreate the whole database schema (we use a separated database for testing purposes as explained here).

The representation

Now, that we have our Order class you might wonder how and where to de-serialize the chunk of xml we see at the beginning.

This broadly discussed but at some point there is some level of agreement; Entities are not DTO (and representations are more or less like DTOs).

As you can see, this is quite different to our domain entity and in the long run the difference will be bigger because Representations doesn’t have methods.

After I wrote those classes with their properties; the tests that we have to fix is this one:

[Test]
public void CanDeserialize()
{
    var xml =
        @"<?xml version=""1.0""?>
<order xmlns:xsd=""http://www.w3.org/2001/XMLSchema"" xmlns:xsi=""http://www.w3.org/2001/XMLSchema-instance"" xmlns=""http://restbucks.com"">
  <location>inShop</location>
  <cost>100.4</cost>
  <items>
    <item>
      <name>latte</name>
      <quantity>0</quantity>
      <size>large</size>
      <milk>skim</milk>
    </item>
  </items>
</order>";
    var representation = XmlUtil.FromXmlString<OrderRepresentation>(xml);
    representation.Satisfy(r =>
                           r.Items.Any(i => i.Name == "latte"
                                            && i.Preferences.Any(p => p.Key == "size")
                                            && i.Preferences.Any(p => p.Key == "milk")));
}

The resource handler

This test validate that if the customer does a POST of a product that doesn't exist, then the resource handler must return 400 and a meaningful ReasonPhrase:

[Test]
public void WhenAProductDoesNotExist_ThenReturn400AndTheProperREasonPhrase()
{
    var resourceHandler = CreateResourceHandler();
    var orderRepresentation = new OrderRepresentation
    {
        Items = { new OrderItemRepresentation { Name = "beer" } }
    };

    var result = resourceHandler.Create(orderRepresentation);

    result.Satisfy(rm => rm.StatusCode == HttpStatusCode.BadRequest
                      && rm.ReasonPhrase == "We don't offer beer");
}

This test does another validation:

[Test]
public void WhenItemHasQuantity0_ThenReturn400AndTheProperREasonPhrase()
{
    var resourceHandler = CreateResourceHandler();
    var orderRepresentation = new OrderRepresentation
    {
        Items = { new OrderItemRepresentation { Name = "latte", Quantity = 0 } }
    };

    var response = resourceHandler.Create(orderRepresentation);

    //NOTE: I am not sure if the proper response is NotFound or BadRequest. It is not clear in the book.
    response.Satisfy(rm => rm.StatusCode == HttpStatusCode.BadRequest
                        && rm.Content.ToStringContent() == "Item 0: Quantity should be greater than 0.");
}

and so forth. When the order is ok:

[Test]
public void WhenOrderIsOk_ThenInsertANewOrderWithTheProductsAndPrice()
{
    var orderRepository = new RepositoryStub<Order>();
    var handler = CreateResourceHandler(orderRepository);
    var orderRepresentation = new OrderRepresentation { Items = { new OrderItemRepresentation { Name = "latte", Quantity = 1 } } };

    //act
    handler.Create(orderRepresentation);

    var order = orderRepository.RetrieveAll().First();
    order.Satisfy(o => o.Items.Any(i => i.Product == latte && i.UnitPrice == 2.5m && i.Quantity == 1));
}

[Test]
public void WhenOrderIsOk_ThenInsertANewOrderWithTheDateTime()
{
    var orderRepository = new RepositoryStub<Order>();
    var handler = CreateResourceHandler(orderRepository);
    var orderRepresentation = new OrderRepresentation { Items = { new OrderItemRepresentation { Name = "latte", Quantity = 1 } } };

    //act
    handler.Create(orderRepresentation);

    var order = orderRepository.RetrieveAll().First();
    order.Date.Should().Be.EqualTo(DateTime.Today);
}

[Test]
public void WhenOrderIsOk_ThenInsertANewOrderWithTheLocationInfo()
{
    var orderRepository = new RepositoryStub<Order>();
    var handler = CreateResourceHandler(orderRepository);
    var orderRepresentation = new OrderRepresentation 
                                    { 
                                        Location = Location.InShop, 
                                        Items = { new OrderItemRepresentation { Name = "latte", Quantity = 1 } } 
                                    };

    //act
    handler.Create(orderRepresentation);

    var order = orderRepository.RetrieveAll().First();
    order.Location.Should().Be.EqualTo(Location.InShop);
}

The last test for this use case is very interesting:

[Test]
public void WhenOrderIsOk_ThenResponseHasStatus201AndLocation()
{
    var orderRepository = new Mock<IRepository<Order>>();
    orderRepository.Setup(or => or.MakePersistent(It.IsAny<Order[]>()))
                   .Callback<Order[]>(o => o.First().Id = 123);

    var handler = CreateResourceHandler(orderRepository.Object);

    //act
    var result = handler.Create(new OrderRepresentation { Items = { new OrderItemRepresentation { Name = "latte", Quantity = 1 }}});

    var expectedUriToTheNewOrder =
        resourceLinker.GetUri<OrderResourceHandler>(or => or.Get(0, null), new { orderId = "123" });

    result.Satisfy(r => r.StatusCode == HttpStatusCode.Created
                                  && r.Headers.Location.ToString() == expectedUriToTheNewOrder);
}

It means that after creating the order, the response status must be Created (201), and there must be a Location header.

The protocol is very clear on this (section 14.40):

The Location response-header field is used to redirect the recipient to a location other than the Request-URI for completion of the request or identification of a new resource. For 201 (Created) responses, the Location is that of the new resource which was created by the request. For 3xx responses, the location SHOULD indicate the server's preferred URI for automatic redirection to the resource. The field value consists of a single absolute URI.

A client application can pull the representation from the header location and get more details of the resource it just created, but that is for my next post :).

Updated Wiki: Preparing the environment

jfromaniello — Tue, 31 May 2011 16:28:21 GMT

Before I get to the core concepts; here is a short explanation of what you have to do to get the project working on your machine:

Clone the codeplex repository with mercurial
Create an empty database in a Sql Server instance
Open the Visual Studio solution
Edit the connection string named “Restbucks” in the Web.Config (web project) and App.config (test project) files.
Run the test in RestBucks.Tests.DataInitializer, named InitializeData; this will create the database schema and populate some data.

If you want to run the full suite of tests, you need to follow these two additional steps:

Create another empty database
Modify the connection string named “Restbucks_Tests” in the App.Config (test project) to point to the database that you just created.

Now you can run the application! You will learn how it works in the following post.

Note: all the dependencies were added with nuget, the dependencies are not under version control. The first time you build the solution, nuget will fetch all the dependencies from the main repository as explained here. You don’t need nuget installed to do this, simply build the solution as any other solution.

Contributors are welcome!

Want to contribute to this sample or show would you implement other RESTful patterns? follow the following steps:

Fork the repository in codeplex (you will need a codeplex account)
Make changes to your local copy (clone in Mercurial jargon)
Do as many commit as you want, (within a new branch is the preferred way; but not mandatory)
Push your changes to your fork in codeplex
Ping me in twitter, mail or wherever you want so I can see your changes (preferred codeplex discussion list)

Updated Wiki: Overview

jfromaniello — Tue, 31 May 2011 15:29:54 GMT

In this post I will give a brief overview of RestBucks on Net.

Use cases

These are the use cases implemented so far:

The customer makes an order
The customer changes an order
The customer pay the order
The customer query his order
The customer cancel his order

As well, as:

The barista prepare an order

Implementation details

A relational database to persist the data.
An Inversion of control container
An Object to relational mapper
Test Driven Development.
As well as other well known patterns that we will discuss in upcoming articles.

The tools I have used for this example were not randomly chosen. They are ready to be used in real world applications.