Adds support for the Hal Media Type (and Hypermedia) to Nancy
C# Ruby Shell
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

Nancy.Hal NuGet Badge

Adds lightweight support for the Hal+JSON media type to Nancy

For Nancy 2.0.0-alpha support there is a pre-release package available.

What is Hal?

Specification

What Nancy.Hal does

  • Allows Nancy web services to return hal+json formatted responses
  • Allows your web services to return plain old JSON/XML representations of your POCOs
  • Does not require your models to inherit from any base classes or implement any interfaces
  • Uses a fluent declarative syntax to configure the links used to decorate your hypermedia resources
  • Works with whatever JSON Serializer you are using with Nancy

What Nancy.Hal does not do

  • Handle hal+xml responses
  • Deserialize Hal representations back into POCOs (HAL is a serialization format, but says nothing about how to update documents)

Get started

  1. Install the Nancy.Hal package
Install-Package Nancy.Hal
  1. Create a HalConfiguration instance.
var config = new HalConfiguration();

//simple example - creates a "self" link templated with the user's id
config.For<UserSummary>()
    .Links(model => new Link("self", "/users/{id}").CreateLink(model));

//complex example - creates paging links populated with query string search terms
config.For<PagedList<UserSummary>>()
      .Embeds("users", x => x.Data)
      .Links(
          (model, ctx) =>
          LinkTemplates.Users.GetUsersPaged.CreateLink("self", ctx.Request.Query, new { blah = "123" }))
      .Links(
          (model, ctx) =>
          LinkTemplates.Users.GetUsersPaged.CreateLink("next", ctx.Request.Query, new { page = model.PageNumber + 1 }),
          model => model.PageNumber < model.TotalPages)
      .Links(
          (model, ctx) =>
          LinkTemplates.Users.GetUsersPaged.CreateLink("prev", ctx.Request.Query, new { page = model.PageNumber - 1 }),
          model => model.PageNumber > 0);


//per request configuration
public ExampleModule()
{
    this.Get["/"] = _ => 
    {
        this.Context
            .LocalHalConfigFor<Users>()
            .Links("relation", "/link");

        return 200;
    };
}
  1. Register it in your application container.
//TinyIOC
container.Register(typeof(IProvideHalTypeConfiguration), config);

//NInject
kernel.Bind<IProvideHalTypeConfiguration>().ToConstant(config);
  1. That's it! Don't forget to set your Accept header to application/hal+json

Acknowledgements

This library could not exist without the work and ideas of others: