Short and sweet introduction to RESTful services

I have heard a lot about REST and RESTful services but never have had the opportunity to work in project that uses that architectural style of working. So sadly I haven’t learned it.

Here is a short and sweet introduction to the subject that explains REST in a good way.

So – as I understand it – it’s just HTTP. The way HTTP is meant to be (URL to each resource, stateless, hyperlinks between resources and usages of the HTTP verbs). I like the simplicity.

The value of an ubiquitous language

A few days back we had a mail-wise discussion on the subject; why should we care about an ubiquitous language?

For me the question falls into two parts; for the whole company/business or for the application.

• An ubiquitous language or common domain model for a complete business have never felt right with me. I know, I know; I have been defending it, striving for it and even forced it on some customers – but I don’t like it!
  It will never work! The same entity, (customer) for example, can have very different meanings in different context.
  A better and much more detailed discussion can be found here:
  • http://devlicio.us/blogs/casey/archive/2009/05/14/commercial-suicide-integration-at-the-database-level.aspx
  • And in Dan North’s excellent SOA for the rest of us
• An ubiquitous language for an application is a completely different thing and is something that I think should be strived for. But that basically means that all the members of the team (customer, analysts, developers, code, tester, documentation) referrers to the same things with the same name.
  For me it has to do with speed and accuracy in communication within the team.

But don’t take it for me. I did a quick search through the net and found some articles that gives better points on why an ubiquitous language is a Good Thing:

• It starts and ends with Eric Evans book: Domain Driven Design. With Google Books you can read the relevant chapter here.
• James Shores take on the subject, with a Haiku even…
• Kent Becks words
• A more formal definition and description, from www.domaindrivendesign.org
• A long but worthwhile read on the subject. Search on Eric Evans to go to good parts. I told you that it starts and ends with him… ;)

Oh yeah – thanks to Oscar and Jocke for the discussion.

Some great SOA – articles

I am preparing a talk on SOA. That always scares me since it’s such a big topic. Who among us would want to answer the question “What is SOA?”

OK – in my preparations I found some great resources.

• My new house-god Dan North has made this fun and easy to follow introduction.
• A lot of different stuff on Wikipedia is a good starter. Here are some articles on SOA, Enterprise service bus and SOA Governance that I found useful as introduction.
• Here is a really good discussion on why a common domain model is no good idea.

Validating WCF-messages with WSDL

When you first think about it, it's quite strange that no validation, takes place out-of-the-box ,against the WSDL that describes a service (asmx or WCF). Then you (read: I) forget it and all of a sudden you don't think that much about it; the generated proxy or services code doesn't contain logic. Period.

It's even more so when you only create services that is generating WSDL when asked. BUT (and it's a big but ;)) - when you start doing Contract First you are actually specifying the WSDL first and then generate the code... then the question arises again.

I mean you're specifying things in the WSDL that doesn't get generated into the code. Things like format, lengths and stuff like that. It's a bit strange that it's lost. And the best scenario is that it's simply validated when the request is received.

Lo and behold - here is mr Skonnard with a brilliant solution. Here are some other articles brushing on the same subject.

Thanks to Fredrik for finding this, especially since I serious doubted that it could be done. We are trying to implement it now - I'll get back to you with our experience in a while.

WCF, WSDL and differences from web services

I'm back after a four week vacation (oh yeah - us Swedes really has things going for us). More about the vacation later.
First thing to learn this "season" is that the WSDL generated by WCF (Windows Communication Foundation) services differs from the one generated with ASMX web services.

The main difference is that the WSDL is generated with some kind of virtual links. That is; parts of the WSDL-file is retrieved using a different URL. For example:
schemaLocation="http://localhost:3236/Bokforing.svc?xsd=xsd0

This seems to be working fine in Visual Studio 2008 (and hopefully in 2005 also), since they are capable of navigating such references. But there are problems when you want to send the WSDL-file to someone as an attachment, or in other environment that can't navigate such links.

Fortunally Christian Weyer has a suggestion on how to solve this. There are also some other very useful stuff in there on how to use namespace correctly in the attributes of WCF.

Since I am forced to use VB.NET I translated the code using this excellent tool found at Developer Fusion

It is quite tricky but can all be done with base-classes so that not every developer in the team needs to worry about it...

Two gotchas appeared for me;

1. The @ServiceHost Factory is a bit strange since is doesn't show up in intellisense. It works quite fine though. Read more about it here, and here.
2. The loop found in the private method
   RemoveXsdImports was quite tricky to translate into VB.NET since its using a kind of looping that not is supported by VB.NET. Also the Developer Fusion tool didn't translate it correct.
   Here is the code:
   
   
   Private Sub RemoveXsdImports(ByVal schema As XmlSchema)
   Dim i As Integer = 0
   While i <>

Web Service Factory

Following a tip from Robban I've been checking out the Web Service Factory tool from Microsofts Patterns and Practices gang.

Robban and I were discussing the use of Contract First design in an upcoming project and I was interested to see if there were any good tools out there.

Well as it turns out there are good tools... but the one that seemed to be most complete was the Web Service Factory (horrendous name, by the way...). Also for us Microsoft-coders the PoP-gang is well-known and often delivers with great quality.

I have now been checking it out and it is good. Here is some of the stuff I've been checking out

• The home of Web Service Factory (and the Codeplex home)
• Introduction
• A video showing off some features

I am not yet convinced that we will go this way (the completeness is maybe too great fiddling with servers etc.) but it sure looks good.

Presentations

Today is kind of a special day at work. After the normal work day we have invited my customer to Avega for an evening of some, hopefully interesting and fun presentation.

Why I am hoping this is because I am doing the presentations, and the "fun" part.

The first part is a SOA-presentation together with a colleague - Robert Södergren. Here we will try to answer the not-so-easy-answered-question "What is SOA?".

For the fun is something even more nerve-wrecking; I often take the opportunity to play my euphonium and tell people little about the Salvation Army. Nothing special there. But this time I have chosen to end the session by playing the infamous Carnival of Venice, by Arban.

I know - it's my own choice and all that - but it was a bit harder than I expected to get it up to "wow"-factor. I am not quite sure I am there yet - to be honest. I'll get back to you.

How to get equivalent proxy-classes to implement a shared interface

After reading the great patterns book i was talking about earlier i soon ran into a problem that at first seemed pattern-like but was not after some examination.

The case that we are integrating against a back end AS400 system, via Microsoft Transaction Integrator. The "problem" is that the department that is responsible for the integration is creating a web service for each program ("method") we are accessing. I brushed on this in an earlier post about naming those web services.

A lot of the stuff we are sending back and forth are equivalent but not the same, for example an header that all methods expect. They are equivalent but not the same since they are located in different namespaces, since the header are generated once for each web service.

So what we wanted was to create an interface that all the headers could implement. To create the interface was not hard. I simply made an interface that declared all the properties of the header. I called the interface... IHeader (duh!)

But to get all the generated header classes to implement IHeader was another thing altogether. Luckily the generated classes of the proxy are partial classes. So we created another partial class with the same name, in the same namespace. That partial class implemented our new interface.

Now we just had on big obstacle to get over; implementing the interface. Implementing interfaces in VB.NET is explicit. That mean that we explicitly had to code the call the underlying implementation, in our partial class, to get the whole thing to work. We are counting on ca 40-50 methods and web service so that would be all lot of dumb code.

Even more stupid is that all the code already is "implemented" since we know that all our header classes has the properties declared by the interface. So we had to do the whole thing in C#, which supports implicit interface implementation (whoa - fancy phase alert). So nice!

The whole thing collapses to a single line of code (excluding namespacestuff). Here is an example:

namespace LF.Tjanster.Sak.DataAccess.TI.Migg.ListData.HamtaVerksamheter
{
    public partial class WS_Migg_Header : IHeader { }
}

I don't know if this is a pattern but is sure is nice. By using partial classes and implicit interface implementation (again? I'll switch to writing books soon...) we solved a quite hard problem in a very nice way.

Now we can treat the headers uniformly by passing an interface instead of an implementation ("Classes are dead. Long live interfaces").

And we'll probably use the same trick for exception handling, and logging, and ...

What is SOA? What is SOAP-RPC?

The now almost age-old question; "but what is SOA then?" has been out for debate at the office where i am right now. It must be stated that this is a gang of developers and quite often the questions bubbles down to; "but this line of code then, is this SOA?".

I took some time over the weekend and though about it - and came to the conclusion that you cannot answerer that question because the question is not correct in itself. SOA has to do with switching position and behold your world from another angle, was my conclusion.

And lo and behold; today i found an article that explained a lot of stuff surronding this for me: http://wisdomofganesh.blogspot.com/2008/02/deciding-characteristic-of-soa.html

Great explanation of the differences between SOA and SOAP-RPC.

Naming service reference to get namespace-like behavior

In my current project we are accessing a legacy system using Microsoft Transaction Integrator. Luckily for us we don't have to write any of that stuff, that is done by another team who exposes the objects and methods in the legacy system as web services.

However - they have chosen to encapsulate each object.method as one web service. Since we will have about 50 methods to call it we be ... 50 web service references for us to keep track on.

That is not a problem if it wasn't for the namespacing. There are a lot of wsGetBusinessCodes and wsUpdateInsurance namespaces running around in our code.

Yesterday we found a "solution" to how to organize the web service references on our, the client, side - and still let the server side publish the web service how they like. The solution is quite simple;

as it turns out you can include points (".") in the name of a web service reference. This gives us an opportunity to name the service reference in a namespace-like manner. For example we use:

Dim a as TI.SystemName.ObjectName.MethodName.Class

When we add many references in the same way they will be organized in a nice way. Simple and powerful - that how we like it.

Great project started

OK - this last two weeks has been intense. I've started a new project at my customer and it is wild; i am Scrum master (nothing new there;) it's the only way to fly) in a pilot project to create a true SOA (Service Oriented Architecture) at my customer (a big Swedish insurance company).

I am very humbled by the magnitude of the project and where this can take us... At the same time it is so fun; we get to set stuff about the technology (SOA, WCF, Visual Studio 2008, TDD - the works) that i didn't dream of just a few months back. Also it is great to see the true use of SCRUM - it is rocking, as it of course would.

But it has come to my attention that readers of the blog are missing some personal comments on non-IT stuff. This is trademark Marcus Hammarberg behaviour - i get swallowed by new thing.

But i wont leave you hanging out there with nothing to do... So here above are some short postings on interesting things that have happened during the week.

Credentials passing in SOA-solutions for .NET

So finally i got the opportunity to write some about a finding that has solved a major problem at my customer. A big thank you to Fredrik A and Micke for the help on this solution.

The problem is a probably a common one; we have some external web applications (that is: reachable from the Internet) that uses some functionality from internal web service. These internal web service in turn calls a database. The problem probably arise in many SOA solutions since credentials will flow from server to server.

Since the users of the external applications may be anonymous or logged into a portal we can't send the user credentials all the way to the database.

So we thought that making the calls, to the internal web services, under system account would solve the problem. But then the double hop problem kicked in and the credentials will "disappear" when going to the database, resulting in the dreaded "User ('null')" error message from SQL Server.

So far the problem, the solution was to do a Impersonate when the internal web service executed. I first thought that this was impossible, since you actually have to change the credentials for the user running the current thread. However i was corrected via the following article which uses some Windows API to do a impersonation.

In our solution we are using that functionality in such way that the external web applications are making the request to the internal web applications under account that only has rights to run the web service. In that the request a SOAP Header is sent that describes the application and the type of operation request. The internal web service use the information in the SOAP Header to do a Impersonation of a suitable system account.

This works out very well indeed and is a much cleaner solution then others I've seen. The impact on the code is as small as sending the SOAP Header and then one using-statement in the internal web service to do the Impersonation.