Generating Hypermedia links in a Web API

Question

I'm curious to know how others have dealt with the issue of generating hypermedia links for their web APIs? Specifically, I'm using ASP.NET Web API, and am torn between having operations return hypermedia-related types, or returning the resource itself, and having the hypermedia stuff happen later in the pipeline. That is, do people tend to do things like:

public Resource<Order> GetOrder(int id) { 
  return new Resource<Order>() {
      Content = new Order(),
      Links = new LinkCollection<Order>() { new AddOrderLink(), new UpdateOrderLink()}
  }

Or something more like

public Order GetOrder(int id) { return new Order(); }

And then add hypermedia links inside an HttpOperationHandler or custom formatter or something?

If the approach is more like #2, how do you know what links to generate? Just have some standard set of links that get generated for all Order objects? Attributes decorating various operations in OrdersController?

Knighterrant

Addendum: I've read over Glenn Block's post about hypermedia in Web API (codebetter.com/glennblock/2012/01/08/…) and while he seems to favor generating the links in-operation (similar to example 1 above), I feel like the "middleware" route he mentions towards the end feels more natural. – Knighterrant

look at the presentation from ammy at teched newzealand channel9.msdn.com/Events/TechEd/NewZealand/2013/DEV305 her solution is promising for hypermedia with web api also look at here github sample code – Tomtoma

Answer 1

I prefer option two (adding the hypermedia links later in the pipeline) and blogged about doing this yesterday.

The solution was to "enrich" my resources with hypermedia links before they are returned to the client using a message handler.

Perspicuous

This is really cool, Thanks for sharing. We used extension methods and it was more of cookie cutter code that accounted for 1 line of code in the action method. I like that you have the resource being returned and can add or not add hypermedia based on context. – Fujimoto

Answer 2

You can use the Hyprlinkr from github

I'm planning to use it in my next project as it seens to be nice and easy to do it and you can get it via nuget package.

Choice

So Hyprlinkr is a good solution for actually generating the links -- when you know what links you want to generate. My Question was more around "how do I know which links I need to generate", rather than "how should I generate them?" Either way, Hyperlinkr does help solve the problem once you get to the "how" part. – Knighterrant

Answer 3

In answering this question, it's instructive to look toward the ASP.NET MVC approach to handling this, since ASP.NET MVC may be viewed as a text/html-constrained version of Web API (manual content negotiation notwithstanding), and since it obviously heavily influenced the design of Web API.

Basically, we can use custom formatters to vary the representations based on the route or an action attribute. This is informed by the way ASP.NET MVC separates views from models. In an ASP.NET MVC project, a single model can be rendered by various view templates. Each of these view template essentially "hard-codes" transitional links (anchor, form, and link elements) into that particular representation of the model. The selection of view template is driven predominately by convention (controller and action name), but can also be hard-coded in the action.

The view engine and view-finding convention in ASP.NET MVC can be considered a custom Web API formatter. This can be generalized such that, for each supported media type, a custom formatter uses route details--and optionally an attribute applied to the invoked action method--to define the resource state. (Under this convention, there is benefit in choosing action names that reflect the state of the resource.) Once the formatter knows the state of the resource, it can delegate to state-specific formatting code. In this code is where state-specific links would defined.

This state-specific formatting code could also delegate to other subformatters, much the same way Razor views support composition of partial views.

Erythema

Answer 4

I've added my solution here

It uses class and property attributes in combination with an ApiController extension method to populate a ResourceLink object in your entity. It can also populate links for any collection properties. It's not the finished article but it is quite intuitive and will make a good start.

Casmey