Tiger.Hal 2.0.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package Tiger.Hal --version 2.0.0
NuGet\Install-Package Tiger.Hal -Version 2.0.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Tiger.Hal" Version="2.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Tiger.Hal --version 2.0.0
#r "nuget: Tiger.Hal, 2.0.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Tiger.Hal as a Cake Addin
#addin nuget:?package=Tiger.Hal&version=2.0.0

// Install Tiger.Hal as a Cake Tool
#tool nuget:?package=Tiger.Hal&version=2.0.0

Tiger.Hal is an ASP.NET Core library for defining declarative transformations from values to their HAL+JSON representation. It allows these transformed values to be served when a client includes the content type application/hal+json in a request's Accepts header. This library conforms to a conservative subset of the JSON Hypertext Application Language draft specification.

Limitations will be called out explicitly in this document.

Why You Want It

The web is built on hyperlinks. RESTful APIs are also built on hyperlinks. XML RESTful APIs have a common, frequently-used way to express relations between resources: XLink. HAL+JSON brings the ability to link resources (and the ability to define the nature of those links) to JSON.

Given a response from an API that looks like this:

{
  "id": "c06f1945-a68a-4a6f-a7a9-5c35a0966abc",
  "itemId": "23b73042-9dec-4587-a21f-4c4c25d8df3c",
  "composition": "vertical",
  "size": 42
}

…how can further details on the "item" associated with this resource be retrieved? If this response body came from sending a request to https://example.invalid/printJobs/c06f1945-a68a-4a6f-a7a9-5c35a0966abc, then a fair guess is https://example.invalid/items/23b73042-9dec-4587-a21f-4c4c25d8df3c.

Or possibly https://another-team.example.invalid/items/23b73042-9dec-4587-a21f-4c4c25d8df3c

Or possibly this item does belong to Another Team, but in a different environment…

Or possibly literally anywhere else on the entire web. There's no way to reverse-engineer, guess, or construct a URI to a resource given only the resource's ID. At least, not without external, fragile information.

A response that looks like this would be much better:

{
  "_links": {
    "self": { "href": "https://example.invalid/printJobs/c06f1945-a68a-4a6f-a7a9-5c35a0966abc" },
    "https://relations.example.invalid/item": {
      "href": "https://another-team.example.invalid/item/23b73042-9dec-4587-a21f-4c4c25d8df3c"
    }
  },
  "composition": "vertical",
  "size": 42
}

Huh, look at that. Another Team uses singular resource names in their URIs. But because the entire URI is available to be followed without manipulation, clients of their API don't need to know that. (In fact, Another Team uses singular resource names when accessing a single resource, but plural resource names when accessing an index. Tricky.)

When API responses contain link relations, following the chain of data becomes as easy as clicking links on a web page.

Operations

In order to set up a HAL+JSON transformation, this library provides four operations. For developers familiar with the specification, some of these operations may be surprising.

There are no operations that correspond to, represent, or manipulate the curies link relation. This functionality is not supported in this library. The specification is very confused when it comes to CURIEs and link relations, and it's better off pretending that they don't exist.

Going Further

This is only an overview of the operations available in Tiger.Hal. The public methods of the library are extensively annotated with documentation comments, so they should provide finer detail on each operation and it overloads.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 is compatible.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
7.0.1 24,994 8/5/2021
7.0.0 920 6/3/2021
7.0.0-rc3 935 3/25/2021
7.0.0-rc2 242 3/24/2021
7.0.0-rc1 379 3/11/2021
6.0.0-pre1 2,251 7/3/2019
5.0.0 25,252 11/6/2018
4.0.0 1,272 9/26/2018
4.0.0-preview2 587 9/26/2018
4.0.0-preview1 593 9/24/2018
3.0.0 1,801 7/17/2018
2.0.2 5,510 3/19/2018
2.0.1 2,340 1/16/2018
2.0.0 1,930 1/15/2018
1.0.0 1,884 11/27/2017

⁃ Everything is new!