Client does not know about the Server types

Topics: Web Api
Dec 27, 2011 at 3:46 PM

I am following along in the .6 release of the WCF Web API chm file.  I have built my service and everything works fine when I access it via IE.  But when I create my console app, I don't understand how the client can know about the "contact" type.  Sure I can add a reference, but how would some other client out there in the world know abou the types?

List<Contact> contacts = resp.Content.ReadAs<List<Contact>>();
How would a client know about changes to the Contact class?
Thanks.
Dec 27, 2011 at 9:29 PM

Web APIs shouldn't be about concrete class types, they should be about a data interchange format. That may looks very much like the way we model a "class" in a class-based language, but that's really an implementation detail. For example, if the client is a browser using JavaScript, I would never actually create a class, at least partly because JavaScript isn't a very strong class-oriented language. The dynamic nature of JavaScript means that I could just consume the JSON without regard to any specific "type".

On the client side, if you're using a strongly class-oriented language (like C#), you're free to invent a class which maps well into the projected data structure... and you're free to do this, regardless of the implementation language of the server. The two things should be unrelated to one another.
Dec 27, 2011 at 9:34 PM

Brad, thanks for those comments.  So in my C# win8 metro client, I will just create a class that minics the class on the server.  I am just trying to figure this out compared to the WebApi oData DataSvcUtil that creates classes that are the same as on your server.

What is your method of accessing a database from your test metro apps?  Have you come to an conclusions on a good way to do it, considering we can't use System.Data in the client?

Dec 28, 2011 at 12:00 AM

Personally, I've done exactly zero Metro programming so far. :) Hopefully someone else can chip in their opinion...

Dec 28, 2011 at 2:34 PM

Brad, I guess another question is how would someone consuming my web api service know what the data looked like?  Before we had wsdl files that descirbed the data, what is a client to do now?  I know what the data looks like, because I created the service and am consuming it.  I feel I am missing something here.

Dec 30, 2011 at 8:04 AM

If you're being any kind of RESTful, think in terms of your service providing access to your resources, but instead of exposing direct access to those resources, you return representations (e.g. XML and/or JSON based) of those resources.

Name, define and document "media types" for the resource representations that your service returns.  E.g. "application/vnd.blah+json".  You don't have to register these media types publicly, they can be private to your service.  But they do need to be documented, and that documentation needs to be made available to clients.

Now consider rules 3 and 5 in the bullet-point list in this (in)famous blog entry by Roy Fielding:-

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Actually, consider all the rules given there, but 3 and 5 seem most pertinent to this dicussion.

Rule 3 starts: "A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources"

Rule 5 starts: "A REST API should never have “typed” resources that are significant to the client."

Even if you don't want to be totally RESTful, these are rules (aka constraints) that are useful for many kinds of API/service that are exposed over HTTP/the web.

I find it's useful to follow REST rules, even if I call my service a "Web API" rather than a "REST service".

You asked how a client would know about changes to the Contact class... well, I recommend the "RESTful Web Services Cookbook" which has a whole section on extensibility and versioning.

Dec 30, 2011 at 2:37 PM

Andrew thank you for your thoughts, they have given me more to chew on and clarified some of my thoughts.  I have a bunch of the oriely cookbooks but not that one, ...heading to amazon.

Terrence

Dec 30, 2011 at 4:33 PM

That cookbook is really great, but probably best used as a reference once you have understood the fundamentals of the REST architectural style.  For a modern treatment of the REST style (i.e. post 2008, and fully embracing the "hypermedia constraint") I recommend "REST in Practice" - another OReilly book.  RiP is probably the place to start.

Coordinator
Dec 30, 2011 at 4:58 PM

Rest In Practice is a great place to start.

Another place i would highly recommend is to read Mike Amundsen's blog as it is a go to resource for information on building hypermedia based systems. A lot of the content on his blog is fodder for his new book on building hypermedia based systems with HTML 5.. I have read an early copy and it is excellent.

Thanks

Glenn

Dec 30, 2011 at 5:02 PM

Great, thanks for those pointers.