I was working on some reporting stuff and thought I had an issue where I needed to have elements instead of attributes. I found that the following XSLT would do that conversion for me.
Turns out that I didn’t need it, but I figured it would be handy to keep around.
I need to write this somewhere or I’ll forget how to do it. I’ve recently started using branches in hg for my target environments instead of using separate repositories as is recommended by Kiln. I got a request to produce a list of changes that would be going into the next production release and knew there must be a way of doing it in hg. This is what I found,
hg log -r "ancestors(branch(test)) - ancestors(branch(prod))"
-–style changelog > changes.txt
Seemed to do the trick.
A few months ago I put up a site http://hypermediaapi.com with the intention of using it as place to aggregate links to all things hypermedia related. I built the site using Web API because a) I know how to use it, and b) I wanted to prove a point that a Web Site is really just a special type of Web API.
Anyhoo… I ran into an issue because I needed to use the server that was hosting the site for another site that was going to be hosted in IIS. To my great disappointment I discovered that the two don’t play nicely together. Apparently when WCF creates a service on a port, it thinks it owns the port. Stupid really, because it uses HTTPListener under the covers which is quite capable of playing nicely beside IIS.
So, to cut a long story down to a medium length story, I went searching for alternatives. I have built a server based on HttpListener before and although it’s not hard to get something that works, getting something that is robust and works well is a whole lot more work and requires more talent/knowledge than I have time to acquire.
I have tried playing around with Katana a couple of times before and failed. It’s been a moving target for a while with the Owin spec only recently hitting a 1.0 release. I noticed a couple of days ago whilst browsing through some Katana source code a project called OwinHttpListener. I didn’t have time to look at it them, but today I decided to have another look. I went hunting for nugets and came up with nothing that worked, so I decided to seek help.
I read Filip’s post here http://www.strathweb.com/2012/12/running-aspnet-web-api-with-owin-and-katana/ which has some great information but it shows how to run the server from the katana.exe or using a System.Web host. I wanted to be able to create my own console app and then my own Windows Service.
Turns out there is a Jabbr room for Owin and GrumpyDev was there and was kind enough to show me how they are using Owin in Nancy. It turns out, once you get the right Nugets installed, and know the simple incantations, it is dead easy to get a self-hosted console based Web API running on Katana.
The trick is to pull in these two packages.
http://nuget.org/packages/Microsoft.Owin.Hosting aka Katana
http://nuget.org/packages/Microsoft.Owin.Host.HttpListener
There is no explicit dependency between the two, presumably because you can use Owin/Katana with servers other than HttpListener, however, by default Katana tries to use the OwinHttpListener as the default server.
Once you have those packages referenced, there is a class called WebApplication that has a static Start method that will get the server going. The code (which is almost identical to what Grumpydev showed me) looks like,
class Program
{
static void Main(string[] args)
{
var baseAddress = (args.Length == 0) ? "http://hypermediaapi.com" : args[0];
using (WebApplication.Start(baseAddress))
{
Console.WriteLine("Server running on {0}", baseAddress);
Console.ReadLine();
}
}
}
public class Startup
{
public void Configuration(IAppBuilder app)
{
var config = new HttpConfiguration();
HypermediaApiConfiguration.ConfigureSite(config);
app.UseHttpServer(new HttpServer(config));
}
}
The only difference between my code and the code to run a Nancy app is that I have app.UseHttpServer(…) and Nancy has app.UseNancy(). Because I had already built my site to be independent of whether it was Self-hosted or run under Web Host, moving it over to Owin required no code changes at all to my site.
So, http://hypermediaapi.com is now running. It doesn’t have much content on it yet, but I am experimenting with a variety of Web API techniques. For example, if you go do
GET http://hypermediaapi.com/Learning Accept: text/plain
you will get a textual representation of the content. If you go to http://hypermediaapi.com/Learning.atom you will get an atom representation. Most of the pages are served up using Razor templates based on the RazorEngine library. However, I’m also starting to experiment with the Parrot templating engine. The general theming of the site is provided by Twitter Bootstrap which I serve up out of resources embedded in the site assembly.
This is an ongoing experiment to see where self-host Web API falls short when trying to deliver a standard web experience. I’ll keep you posted.
A few of us keep complaining about the way the HTML5 specification is written. The argument we are given is that the HTML5 is written in a more prescriptive form to reduce the ambiguity that exists in the more traditional “declarative” style RFC documents. I’ve spent a fair bit of time reading specs over the last few years and although they were tough to get going with I feel pretty comfortable now.
So, Ben Foster was asking on Twitter about his use of the “alternate” link relation and I decided I go check out the spec. To find the spec I first went here http://www.iana.org/assignments/link-relations/link-relations.xml and discovered that the spec is http://www.w3.org/TR/html5/links.html#link-type-alternate.
Let’s walk through this text…
4.12.5.1 Link type "
alternate"
Shame they decided to use the term link type instead of the standard “link relation”. The attribute is “rel” after all.
The
alternatekeyword may be used withlink,a, andareaelements.
Hmmm, ok. They are defining the use of alternate within the context of a HTML document. That’s unfortunate, but it is their prerogative. It just means that if someone like Ben decides that he thinks the idea of an “alternative” link is useful in his media type then he is free to make up his own rules on what alternative means to him.
The meaning of this keyword depends on the values of the other attributes.
If the element is a
linkelement and therelattribute also contains the keywordstylesheetThe
alternatekeyword modifies the meaning of thestylesheetkeyword in the way described for that keyword. Thealternatekeyword does not create a link of its own.
Oh, a special case. What I think they are saying is if we have rel=”stylesheet alternate” then alternate changes the meaning of stylesheet in a way defined somewhere else. Oh dear, that directly contradicts RFC5988, that states:
Relation types SHOULD NOT infer any additional semantics based upon the presence or absence of another link relation type, or its own cardinality of occurrence. http://tools.ietf.org/html/rfc5988#section-4
Moving on…
Huh? In which element? Just those two media types? No others? To set what value? What are they talking about?
The keyword creates a hyperlink referencing a syndication feed (though not necessarily syndicating exactly the same content as the current page).
How does a keyword create a hyperlink? Do they mean that the alternate link relation indicates that the target of the link will be a syndication feed with the media type designated by the type attribute? Why don’t they say that?
Yay for standards and simplicity. I get to reference my feed three different ways as long as I only use these two predefined media types. Good job we don’t want to use the media type for versioning or anything like that.
The following
linkelement gives the syndication feed for the current page:<link rel="alternate" type="application/atom+xml" href="data.xml">The following extract offers various different syndication feeds:
<p>You can access the planets database using Atom feeds:</p> <ul> <li><a href="recently-visited-planets.xml" rel="alternate" type="application/atom+xml">Recently Visited Planets</a></li> <li><a href="known-bad-planets.xml" rel="alternate" type="application/atom+xml">Known Bad Planets</a></li> <li><a href="unexplored-planets.xml" rel="alternate" type="application/atom+xml">Unexplored Planets</a></li> </ul>
Otherwise
- The keyword creates a hyperlink referencing an alternate representation of the current document.
Ok, so now we seem to be talking about the more general case. Wouldn’t it make more sense to define the general case first and then call out the exceptions that are specific to the nature of HTML? The annoying thing is that the keyword doesn’t create a hyperlink. It is the link, a or area element that tells the user agent that a link needs to be created. The “alternate” link relation provides some meaning to the link. The way this is phrased makes it sound like I could do <span class=”alternate”/> and a hyperlink would be created.
If you follow the links looking for the meaning of these attributes you end up in a section called “4.12.2 Links created by a and area elements”. What about the Link element? If you dig deeper you get nice self-referential statements like “The media attribute describes for which media the target document was designed”. It is interesting that they use the term target as that term is defined in RFC 5988 to mean the resource referenced by the URL of the link. However, HTML defines target completely differently. In fact target can be an attribute of an A or AREA element. But that’s not the target document that they are talking about . Fun times.
If the
alternatekeyword is used with themediaattribute, it indicates that the referenced document is intended for use with the media specified.If the
alternatekeyword is used with thehreflangattribute, and that attribute’s value differs from the root element‘s language, it indicates that the referenced document is a translation.If the
alternatekeyword is used with thetypeattribute, it indicates that the referenced document is a reformulation of the current document in the specified format.The
media,hreflang, andtypeattributes can be combined when specified with thealternatekeyword.For example, the following link is a French translation that uses the PDF format:
<link rel=alternate type=application/pdf hreflang=fr href=manual-fr>This relationship is transitive — that is, if a document links to two other documents with the link type "
alternate", then, in addition to implying that those documents are alternative representations of the first document, it is also implying that those two documents are alternative representations of each other.
I could go on nitpicking about stuff, but I think the point that I am trying to make is that in trying to make these specs “more accessible” and “less ambiguous” I think they have done the opposite. It is true that IETF RFCs are notorious for being dry and dense in their wording. However, they are consistent and so with a little effort to understand the style, you can get quickly get over the initial pain and it becomes much easier to read. The end result are documents that are far more coherent. In my opinion, this effort write documents that lead people by the nose through a nested bunch of “if this then” that logic produces a far inferior specification than the declarations of inter-related facts that are the basis of RFC style specs.
If you are wondering if maybe I just picked out an exceptional example from the HTML spec, I dare you to go and try and grok the “browsing contexts” section… http://www.w3.org/TR/html5/browsers.html#browsing-context
Enjoy!
I recently had the opportunity to be interviewed on the Deep Fried Bytes podcast about practical uses of hypermedia for desktop and mobile applications. Hypermedia is one of those topics that we are all familiar within the web browser, but it tends to get forgotten when people start writing client applications. There are many ways to leverage the declarative layer of indirection that hypermedia brings.
If you listen the the podcast, I’d love to hear your feedback.
I see many questions on Stackoverflow and the MSDN forums where people are having difficulty because the objects they are trying to return from there API are not being serialized as they expect. Consider you have an API action that looks like this:
public Foo GetFoo() { var foo = new Foo(); return foo; }
What are you supposed to do to debug what is going wrong here when your Foo just isn’t serializing as you expect? You could setup a trace writer as is demonstrated by Mike Wasson here. That will show you some very useful information, but maybe not enough.
It is handy to know that the above action is functionally equivalent to the following,
public HttpResponseMessage Get() { // Create the object to return var foo = new Foo(); // Get the default ContentNegotiation service var negotiator = Configuration.Services.GetService(typeof (IContentNegotiator))
as IContentNegotiator; // Negotiate the appropriate formatter based on the request and available formatters var negotiationResult = negotiator.Negotiate(typeof (Foo), Request,
Configuration.Formatters); // Create an ObjectContent that is used to create the HTTP payload var content = new ObjectContent<Foo>(foo, negotiationResult.Formatter); content.Headers.ContentType = negotiationResult.MediaType; //Force the ObjectContent to serialize the Foo using the Formatter content.LoadIntoBufferAsync().Wait(); // Return a HttpResponseMessage with the Content return new HttpResponseMessage {Content = content}; }
The advantage of this method is you can breakpoint and identify what formatter is being selected and you can see the Content object before it is returned. Forcing the content to LoadIntoBuffer before returning allows you to see if a failure occurs during serialization.
If you identify that the correct formatter is being used then you can isolate the problem down in a simple test:
[Fact] public void TestSerialization() { var foo = new Foo(); var formatter = new JsonMediaTypeFormatter(); var content = new ObjectContent<Foo>(foo, formatter); var result = content.ReadAsStringAsync().Result; Assert.Equal("{}",result); }
My guess is that 4 out of 5 times, the problem has nothing to do with the Web API framework at all, but is a limitation of the underlying serializer/parser used by the formatter class.
Welcome to WordPress. This is your first post. Edit or delete it, then start blogging!
When talking about REST, the conversation usually boils down to coupling. REST enables distributed components to evolve independently over long periods of time, and it does this by constraining where coupling can occur.
I’ve made this pitch a thousand times with the blind assumption that everyone had the same understanding of the term coupling. If I was to try and abstractly define coupling, I would say that, it is a measure of how changes in one thing might cause changes in the other. The confusion arises when you start to consider the best place to put the things that might change.
Now, if we consider the following example HTTP requests,
a) GET /server/WidgetsThatAreFunky b) GET /server/Widgets?foo=34&bar=98&sortBy=baz
In these examples, a client is making a request to the server to get a list of widgets that meet the criteria “Funky”.
In my definition of coupling, the first example has very low coupling between the client and the server because the client is simply expressing WHAT it wants and not HOW to get widgets that meet that criteria. If the way we define “Funky” changes, then the server can make those changes and the client just works.
However, I have now run into a number of people who perceive option (b) as having less coupling because the server does not require any knowledge of what the client might want to do with the data. It is the client that determines how the “Funky” criteria is defined. This perspective opens the door to building a generic API for the server and allowing the clients to come up with all different types of unexpected behaviour. I believe this is the essence of why people are building APIs to their web sites. Build a generic API and let the crowds do their magic.
In both cases, changes to the criteria “Funky”, require changing only one component. In the first example, the server needs to change. In the second example the client needs to change.
Here’s the problem. Although option (b) sounds like the most flexible option, it does have a significant number of disadvantages:
Option (b) exposes a much larger surface area of API than option (a), which means there are many more dependencies between the client and the server. However, with option a the client is far more limited in what it can do with the data.
These two options represent to me two fundamentally different approaches on how to build distributed applications.
From my perspective, option (a) is what REST is all about, encapsulating the behaviour of a service behind resources, so that clients are simply expressing their intent. The idea that REST services should be generically re-usable by many different clients, I believe has been skewed from the original intent. REST services should be usable by clients on many different platforms, however, those clients should be trying to achieve primarily the same goals. Where clients are able to do completely different things with services is largely accidently due to the use of the uniform interface, and media types that apply the principle of least power. That’s why its called “serendipitous reuse” and not “planned reuse”.
Option (b) is about exposing data. If you carry it to the logical extreme, you get the Semantic Web. You need intelligent clients and you need servers that can withstand high volumes of unpredictable requests. I see this style as being appropriate for clients that crawl data in batch mode, rather than interactively responding to user requests.
I think the question you need to ask when building a distributed system, is what I am trying to achieve. Am I trying to expose semantically rich data to the world for people to explore and create things from, and do I have a enough computing horsepower/ financial resources to support that? Or am I trying to build the most efficient distributed application that allows a user to achieve a goal, no matter what client platform they are running on?
I’m not convinced that in this case, middle ground makes sense? I think both types of systems have their place, but serve very different purposes. What do you think?
Ever since Microsoft’s first efforts to deliver a REST style framework in .net, back in 3.5, there has been a continuous stream of questions that has asked: how to I add a service reference to that API? How do I generate a client proxy? How do I access the WSDL for the REST service? Can I generate classes from WADL?
For years I have been telling people, that you can’t do that. REST doesn’t work like that. But many developers insist that is what they want, and I believe I understand why they want it. It just feels so friction free.
I may have found a compromise. With the new features in becoming available in ASP.NET Web API and the benefits of a package management system like Nuget (or OpenWrap), I think you can finally get some of the benefits of a RESTful approach whilst keeping things very convenient.
Before I make my pitch, I want to highlight the aspect of REST that we are concerning ourselves with. The REST constraints encourage us to build clients and servers that are very loosely coupled. This allows the client and server to evolve independently and if we do things right we may find that we can use the client to access multiple services and our service could be consumed by multiple different clients.
This decoupling is achieved by focusing on the data that is transferred between the client and server as a first class citizen of the architecture. In the world of RPC, the data that is passed is often simply an attribute of the procedural endpoint rather than a core architectural concern.
The data that is passed between components of a RESTful system are called representations and their contents are described by Internet Media Types. Next time you hear someone tell you that REST doesn’t have contracts, tell them that Internet Media Types are the contracts and there is a public registry of contracts here.
But, I hear you say, the IANA registry doesn’t have a registered media type for Girl Scout to-do lists which I need for my app. You are correct and there are reasons for that, that I am going to completely side step for now. So, how will we achieve REST nirvana if we don’t have a standard media type to use.
Let me reveal to you REST’s dirty little secret. REST doesn’t actually reduce coupling between the client and the server at all. It just moves it. It uses computer science’s most powerful weapon, the “layer of indirection”. By allowing the server to be dependent on the media type and the client be dependent on the media type, the client and server can communicate without being directly coupled. This means you can happily deploy new clients and new servers and as long as you follow a few other rules, nothing should break. The only time you need to be careful is when your “media type” changes. Then you need to update both the client and server.
So how can we manage a chunk of code that is shared between the client and the server? This is where Nuget|OpenWrap can come to the rescue. By creating an independent package we can control the versioning of that component, we provide an easy way for people who want to consume our API to get at our data and they can easily update their client when we push updates.
These days, if an idea is to succeed it needs a cool name, so considering we are still waiting for JetPacks I decided that WebPacks could keep us going in the meanwhile.
Defn: A webpack is binary component that is deployed using a package management system that contains all the data formats that are shared between a Web API and its clients.
In order to build a a WebPack using ASP.NET Web API we need to include two things
I have packaged up a sample WebPack, client and server using the canonical Contact as the shared object and put it here. Feel free to poke around in the code while I tell the rest of the story.
I hear people asking, isn’t this what people normally call a “client library”, or “client SDK”? Not really. The difference is that a WebPack does not contain any information about the resources of the server. It contains no URL information. It does not know what functionality the server API exposes, it only knows the data building blocks of the service. It’s like being provided a dictionary of English words, so that later you can use it to comprehend a written text. The API will use those building blocks to build an application and the glue that holds all the blocks together is the application protocol, HTTP. This is what will allow our server to add and change functionality without breaking clients, because the clients don’t know in advance what the server can do with that data.
One of the beautiful characteristics of RESTful system is that you should be able to follow your nose to discover how things work and what they mean. When a client developer first comes across a link to our API and issues a HTTP GET, there should be information in the response that helps decide what can be done with that information. Or put another way, what contract is that representation adhering too. The rules of HTTP say that the Content Type header in the response should provide the Internet Media Type that defines the contract of the representation body. So, what media type are we going to use?
One option is to go all custom and use
application/vnd.nuget.ContactWebPack+json
I have taken a whole bunch of liberties in defining this media type. I’m supposed to register this media type with IANA before putting it out on the wild web. Using nuget as a vendor name is a little twisted. The other problem with completely custom media types like this is that web browsers don’t have a clue what to do with it. They don’t know that contract so they just offer up the “save as/download” dialog. An alternative would be something like,
application/json;webpack=org.nuget.packages.ContactWebPack
This means that dumb clients like browsers will see it as application/json but our WebPack savvy clients/developers can be aware of which webpack contains the contracts and formatters.
Reviewing what we have covered so far, a API developer should create a WebPack with the contracts and formatters that they wish to share. The API developer can then build a service that exposes resources using these contracts defined in the WebPack. Client developers add a reference to the Nuget package, and use the provided formatters to allow the HTTP client library deserialize the representations into CLR objects.
Over time as changes occur to the service, some changes may require updating the webpack but many others will not. For example as an api grows there are often requests to add new filtered collections and relations between objects. These changes require addition resources to be added to the server, but they do not necessarily require changing the WebPack.
So far I have only talked about using WebPacks to store shared types, but they can also be used to share link relations. Using strongly typed link relations can be an effective way of sharing service behaviours. However, that I will explore in a future post.
I would like to introduce the term WebPack. A WebPack is a shareable implementation of link relations, media types and other types that provides a client application with sufficient semantics to be able to communicate with a Web API.
Depending on how the semantics are shared, a WebPack may be used in a RESTFul (level 3) or Hypermedia API, or it could be used in a HTTP based API.
It should never be required to use an API’s WebPack to consume the API. The WebPack is simply there to make it easier.
A WebPack is different than a API client library in that it does not have any knowledge of the URLs/Resources exposed by the API. However, it may contain information about the “types” of those Resources.
Ideally a WebPack for an API should be as small as possible as it is an indicator of API specific coupling. In a perfect world there would be no need for WebPacks because APIs would just reuse existing media types and link relations to communicate semantics. Until that richness of shared semantics exists, WebPacks allow us to be specific about what semantics are being shared between client and server. WebPacks can be versioned to facilitate evolution of the API without having to resort to all or nothing URL versioning techniques.
I will be talking more about this in the future, I just wanted to lay claims to the term 
.