When I started work at my current employer, about 2 months ago, I made a decision, an important decision. I decided that our core application should not merely have an API. Like, we have this application and, oh, hey, we added on this fancy API too so it can work with other platforms. No, I decided that the whole application should be an API opening it up to any kind of client in the future. To some this is a strange concept. The idea that the client, the center of all user activity, be it a website, a mobile application or a desktop application, as second-class citizens, just icing on the cake, seems backwards. The client app defines the system, right? No. the core of the application is the API, the state of the system exposed via HTTP, or more specifically a web API.

And if you’re going to build an API using the .Net Framework, of course you’re going to use Windows Communication Foundation (WCF). Because, like a good little Microsoft developer, you do what Microsoft says you should do and Microsoft says you should use the only web service framework that’s relevant, which of course is WCF. Okay, more recently there’s WebAPI, but it looks like a solution that’s late to the party if you ask me, but you didn’t, so I won’t share my opinion on that topic.

I’ve worked with WCF since, well since before there was a WCF. Remember .asmx services anyone? From the beginning WCF always felt wrong to me. The reams of configuration, the ambiguous terminology (what channel is your self-hosted endpoint listening on?) and most of all, the whole concept of remote procedure calls. RPC is the Wild West of web services. There’s no rules and no accountability. You’re just making shit up as you see fit and naming things because it works for now.

//Well, we need to get a customer so here we go public Customer GetCustomerById(int id); //Oh, wait, we now need to get the customer by email public Customer GetCustomerByEmail(string email); //Hmm, apparently we need to get the customer by user name sometimes public Customer GetCustomerByUserName(string userName);

I could never really articulate why this type of construct was wrong in the past, but now I think I can. The problem with the above code is that each definition is an after thought. It’s driven by a specific user interface, making the API subordinate to the UI. All you really achieve is that you can now fulfill your UI needs with these cute RPC methods. So really, we’re just using HTTP as a pass-through to fit our UI requirements and that’s really by design. Microsoft is known for this. The reason WCF generates proxies for you (add web reference anyone?) is so that you can work with a web service without feeling like it’s anything other than a standard class. No need to trifle with that whole HTTP thing when we can hide it (sound familiar WebForms developers?).

With many years of experience using WCF and dealing with it’s limitations (there are many more), I decided to research alternative web API frameworks and I arrived at ServiceStack pretty quickly. One thing that really spoke to me about this framework was the initial sell of message-based services over RPC. All I had to see was the code below and it resonated with me instantly (comments added by me for clarification).

//This is the RPC way of doing web services (each is a distinct method) public interface IWcfCustomerService { Customer GetCustomerById(int id); List GetCustomerByIds(int[] id); Customer GetCustomerByUserName(string userName); List GetCustomerByUserNames(string[] userNames); Customer GetCustomerByEmail(string email); List GetCustomerByEmails(string[] emails); } //And this is the message-based way of doing the same thing (this one message is passed to one method) // WITH ONE METHOD CALL* public class Customers : IReturn<List> { public int[] Ids { get; set; } public string[] UserNames { get; set; } public string[] Emails { get; set; } }

Rays of light shone from Heaven and winged beings with glowing haloes circled my desk when I saw that example. It confirmed that long-held nausea I felt when writing voluminous RPC methods was in fact a legitimate point of anxiety. There is a better way. And so, as the newly hired architect, I took a risk. I went with ServiceStack (I did a few weeks of research first) knowing that the whole paradigm would be new to both to me and my development team. But, the fact that my web API would be a first-class citizen, mostly because it would no longer be defined by the UI, made the decision worthwhile.

Since making this choice, I was put on the hook with a very important delivery date for one our ancillary products. Using ServiceStack made meeting that deadline a lot harder for me because I was learning a new framework on the fly. But the nice thing about an open source framework like ServiceStack is that the community support is great. As the deadline approached for this product to be delivered a co-worker asked me if I regretted using ServiceStack. I told him flat out, NO! The learning curve was steep, but the future of this API is bright precisely because this message-based, REST framework is so well conceived. Is it perfect? No, nothing is, but it’s miles ahead of any Microsoft solution I know of.