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?

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.

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.

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.

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.