Now, coming from the .NET world – I thought instantly that I could whip up a service that could host REST in JSON or XML, support multiple encodings, host a SOAP, and remoting (net.tcp) end point too – all effortlessly. Several endpoints all hosting one physical service.
ASP.NET, WebApi, and WCF give these things to me ***easily***. If I wrote a service in this technology, you could consume it from anything – and easily. What technology can’t read: RESTful JSON, RESTful schema-less XML, or SOAP?
In the year 2012, why WOULDN’T you want to offer your API in every format, every style, every encoding, and every language? Answer: if it was hard to do and if the tooling or technology didn’t support it. That’s the case here. The service is written in Java and each additional thing we talked about means the developers actually have to write code. No wonder why they are pushing back so violently!
It kind of dawned on me that I take .NET for granted sometimes. When I look at things like this compared to Java, Ruby, PHP, etc – it really is almost staggering how different they are. I continue to pursue .NET and Microsoft technologies because they are, by far, the best (read: most developer-friendly) technologies that exist. The day that changes, is the day I’ll switch vendors!
So, let’s call my bluff:
“It’s easy!”, I claim. “No problem!”, I suggest.
“Oh yeah?”, I respond, “Let’s just see, mister.”
I started with creating a new MVC/WebApi project and I added a new controller:
In this StuffViewModel, that just contains properties that point to two different data types:
I know this is somewhat non-sensical, but I wanted to have a few layers of data structures. So, when I call my new RESTful webapi:
from a browser, I get XML:
when I call it programmatically, I get JSON (by default):
In fact, by simply setting the content type in my request, I can request XML or JSON and WebApi does that for me automatically:
Next, I was looking at encoding (as in ASCII, Unicode, etc). According to this article, the placeholders are there, but it’s not fully supported in this version. In fact, how it will work is just as you’d expect. You set the “Accept-Charset” to “UTF-32” or “Unicode” for example and it returns the serialized response, encoded that particular way.
In fact, for things like language – that is something you deal with in your code, not so much in the infrastructure. So, I added a couple of properties to my viewmodel class and added this functionality to the controller (just so it’s clear in the response that I “reacted” to the request for specific encodings and languages):
and sure enough, from the client, I do this:
and my response looks like this:
My service is easily able to react to the request.
So – with just a little bit of code, we can pretty easily support output type (XML or JSON.. or some other custom type). In fact, the other emerging standard is to have other content types of like “text/csharp-sample” and that API call will return a C# sample for that call. That would be relatively easy to to (see this page on creating custom Media Formatters). In other words, imagine that your service supports the following content-types:
- application/json – return the result in JSON format.
- text/xml – return the result in XML format.
- text/html-help-docs – returns a formatted HTML document for help on how to use this specific API.
- text/csharp-sample – returns a C# snippet of how to use this specific API
- text/vbnet-sample – returns a VB.NET snippet of how to use this specific API
You might think this is overkill, but wait. Imagine you have a front-end for your API. Your front-end can actually call the ACTUAL API to go get the documentation and samples. So, not only are these a convenience for your consuming developers, you just solved the content-management problem of how to present documentation.
Again, take a look at the custom Media Formatters link, mentioned above – this is a pretty great concept that is available today.
Now, onto WCF. I create a new service, define it like this:
And voila, I have meta-date/discoverability in the browser:
and of course the WSDL:
To handle encodings and languages, I need to make that part of the interface:
Why? Because WCF isn’t just about SOAP and web, I can now host this “service” as a remoting-like net-tcp endpoint, or one of the other non-web endpoint types! So, I’m not guaranteed any sort of web context from my consumer – it needs to be part of the interface.
THIS is the world of services on the .NET platform for the past few years. This represents enterprise-class features coupled with the latest technologies and standards. THIS is what a .NET developer expects to find out in the wild because it’s effortless to do this in .NET.
I expect to be able to consume a service as SOAP, or as a RESTful service in JSON (when using from AJAX) or XML, because it’s easier to work with from .NET code. I expect services to support encoding and language preferences too.
On the .NET platform you CAN very easily host this ONE service over all of those different endpoints. I spent probably 10 minutes on this sample and it does most of what I set out to do.
In my professional opinion, if you are working with a technology that can’t do these things, in the year 2012, you’re putting your effort into the wrong technology.