Service-Oriented API implementations

It’s quite common for our systems to need to expose an API for external parties to call that isn’t exactly aligned with our service boundaries – at least, when you follow the “vertical services” model rather than the “layered services” approach. I’ve blogged many times about the problems with layering, so I won’t go into that now beyond to say that you really, REALLY, should avoid it.

A short intro to SOA, done right

In the “vertical services” approach I espouse, you often see components from multiple services deployed to any given endpoint. While these services usually don’t need to communicate with each other at all, occasionally you’ll see them leaving “breadcrumbs” behind for each other – things like UserId or OrderId in the session. What’s especially important is that these IDs are accessible even before the entity is finalized – this enables each service to collect its own data without needing any other service to know about that data.

In an ecommerce environment, we would see one service owning money, another the product catalog (excluding prices, those would be owned by the previous service), another service owning the customers’ payment info (credit cards, etc), and yet another owning shipping addresses – all of these separate from the one that owns the shopping cart. Let’s call these Finance, Catalog, Payment, Shipping, and finally Shopping – just so that we have something to reference later.

The API

While we can do all sorts of cool browser composition with the UI in our own system, enabling each service to collect and display its own information, if we want to expose an API for clients to call, we wouldn’t want to force those clients to have to make a separate call to each service in order to make a purchase. Instead, we’d want something that looks like:

MakePurchase(Guid orderId, Dictionary cart, CreditCardInfo cc, Address shippingAddress)

In case you were wondering, the service which owns the definition of this API is different from all of the above services – it is a service that is primarily technical in nature and is responsible for things like integration and data transformations. I call this service IT/Ops.

Getting the data from the API to the services

So, we don’t want any of our business-centric services to know about anybody else’s data structures, so that leaves it to IT/Ops to pass the data to them. The thing is that we still want to do that in the most loosely-coupled way possible – with messaging being a good candidate for that.

So, what we’ll do is have IT/Ops send a message containing the data to the other services, but with a slight twist.

Here’s what the code would look like with NServiceBus:

Bus.SendLocal(new Order { Id = orderId, Cart = cart, 
                          CreditCard = cc, ShippingAddress = shippingAddress });

Why the SendLocal?

So that the components from the other services can all run together with IT/Ops in the same process giving a nice tight deployment model.

UPDATE:

If you’re using a transport like RabbitMQ that is set up as a remote broker, the overhead of going back through the broker might not be worth the improved reliability you’d get by going through messaging. In that case, you might want to consider the Domain Events approach. This would give you a similar level of decoupling but then IT/Ops would need to set up an surrounding transaction, well, that is if you want all the services processing to succeed/fail as one unit. If you don’t, you’d probably be better off just sending messages from IT/Ops to endpoints that host each of the components of the other services.

End Update

Before we get to the services, let me show you the Order class – specifically, the interfaces it implements:

public class Order : ShoppingOrder, PaymentsOrder, ShippingOrder
{
    public Guid OrderId { get; set; }
    public Dictionary<Guid, int> Cart { get; set; }
    public CreditCardInfo CreditCard { get; set; }
    public Address ShippingAddress { get; set; }
}

public interface ShoppingOrder
{
    Guid OrderId { get; set; }
    Dictionary<Guid, int> Cart { get; set; }
}

public interface PaymentsOrder
{
    Guid OrderId { get; set; }
    CreditCardInfo CreditCard { get; set; }
}

public interface ShippingOrder
{
    Guid OrderId { get; set; }
    Address ShippingAddress { get; set; }
}

Each of the above interfaces represents the data that each service cares about. Therefore, each service will provide an assembly that handles that message/data and persists it to its database, like this:

public class ShoppingAPIHandler : IHandleMessages<ShoppingOrder>
{
    public void Handle(ShoppingOrder message)
    {
        //persist to shopping service db
    }
}

public class PaymentsAPIHandler : IHandleMessages<PaymentsOrder>
{
    public void Handle(PaymentsOrder message)
    {
        //persist to payment service db
    }
}

public class ShippingAPIHandler : IHandleMessages<ShippingOrder>
{
    public void Handle(ShippingOrder message)
    {
        //persist to shipping service db
    }
}

Since the Order object being sent is a polymorphic match for all of these interfaces, NServiceBus knows to invoke all of these handlers. By the way, if you care about the order of invocation, then you can control that as well (but I won’t get into that here).

Also, since all of these handler assemblies are deployed to the same endpoint, and the Order object is sent just once, this means that all the handlers will be invoked in a single transaction on a single thread – either all of them succeeding, or all failing. Since they’re all connected on the same Order Id, referential integrity can be preserved as well.

Wrapping up

When you are building a system on SOA principles, you’ll often find that you need a service like IT/Ops to handle data transformation and other broker-centric tasks. While much of SOA is based on the Bus Architectural Style – meaning primarily publish/subscribe interaction between services – that doesn’t mean that your business-centric services cannot have their components deployed in the same process.

I’d go so far as to say that if you aren’t deploying components from multiple services in process with each other at least some of the time then it’s quite likely that your service boundaries are probably incorrect.

Anyway, I hope you found this post interesting. Shout out to Slawek who gave me the idea for this post.

By the way, if you’d like to learn more about these kinds of patterns, the next batch of courses is open for registration – but the early bird prices are almost over, so you’d better hurry.

Register for   Denver CO, USA,     Bad Ems, Germany,     Perth, Australia.