Sciensoft.Hateoas 3.1.0

A library to help you achieve HATEOAS using a fluent language and lambda expression for configuring your ASP.NET Core RESTful/Web APIs. Based on the REST application architecture style, Uniform Interface, constraint Hypermedia As The Engine Of Application State (HATEOAS).

The good thing is, there is no need to inheritance or additional code in your models or addition of extra result filters to support its functionality. They all come beautifully out of the box with Sciensoft.Hateoas

Sciensoft.Hateoas threats lambda as first-class citizen, so your configuration starts with a lambda expression. This library DO NOT enforce REST constraints (https://rebrand.ly/restful-explained) or Richardson Maturity Level (https://rebrand.ly/richardson-maturity-model), and this has to be done by you, Sciensoft.Hateoas helps you only with the implementation of HATEOAS in your resource.

Visit https://github.com/higtrollers/Sciensoft.Hateoas for more details and full documentation.

There is a newer version of this package available.
See the version list below for details.

Install-Package Sciensoft.Hateoas -Version 3.1.0

dotnet add package Sciensoft.Hateoas --version 3.1.0

<PackageReference Include="Sciensoft.Hateoas" Version="3.1.0" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

paket add Sciensoft.Hateoas --version 3.1.0

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: Sciensoft.Hateoas, 3.1.0"

For F# scripts that support #r syntax, copy this into the source code to reference the package.

Documentation

Please visit Sciensoft.Hateoas project at GitHub for more details and full documentation.

Features

Self-link generation,
Named Route link generation,
Custom link generation with support to path override,
External links generation,
Configuration with Lambda Expression,
Attribute Routing support, and
Conventional Routing support.

Roadmap

Add support for extending link generation.
Add support to bypass model link generation.
Add support to .NET Authorization.
Add support to Content Negotiation type in the read-model.

Get Started

Sciensoft.Hateoas gets installed using Nuget package manager.

Install-Package Sciensoft.Hateoas

Or dotnet CLI dotnet add package Sciensoft.Hateoas.

Configuration

Using a fluent language, allows you to easily configure by adding the service to .NET Core dependency injection pipeline.

public void ConfigureServices(IServiceCollection services)
{
  services
    .AddMvc()
    .AddLinks(policy =>
    {
      policy
        .AddPolicy<BookViewModel>(model =>
        {
          model
            .AddSelf(m => m.Id, "This is a GET self link.")
            .AddRoute(m => m.Id, BookController.UpdateBookById)
            .AddRoute(m => m.Id, BookController.DeleteBookById)
            .AddCustomPath(m => m.Id, "Edit", method: HttpMethods.Post, message: "Edits resource")
            .AddCustomPath(m => $"/change/resource/state/?id={m.Id}", "ChangeResourceState", method: HttpMethods.Post, message: "Any operation in your resource.")
            .AddExternalUri(m => m.Id, "https://my-domain.com/api/books/", "Custom Domain External Link")
            .AddExternalUri(m => $"/search?q={m.Title}", "https://google.com", "Google Search External Links", message: "This will do a search on Google engine.");
        });
    });
}

Here is how your controller looks like, no additional injection or attribute decoration is required. Please check our Sample Project out!

[Route("api/books")]
public class BookController : ControllerBase
{
    public const string UpdateBookById = nameof(UpdateBookById);
    public const string DeleteBookById = nameof(DeleteBookById);

    [HttpGet]
    public ActionResult<IEnumerable<BookViewModel>> Get()
    { /* Code omitted for simplicity */ }

    [HttpGet("{id:guid}")]
    public ActionResult<BookViewModel> Get(Guid id)
    { /* Code omitted for simplicity */ }

    [HttpPost]
    public IActionResult Post([FromBody] BookViewModel book)
    { /* Code omitted for simplicity */ }

    [HttpPut("{id:guid}", Name = UpdateBookById)]
    public IActionResult Put(Guid id, [FromBody] BookViewModel book)
    { /* Code omitted for simplicity */ }

    [HttpDelete("{id:guid}", Name = DeleteBookById)]
    public IActionResult Delte(Guid id)
    { /* Code omitted for simplicity */ }
}

JSON Result:

{
    "Id": "8f46d29e-6c0d-4511-85e7-b1d7ae42934a",
    "Title": "The Girl Who Lived: A Thrilling Suspense Novel",
    "Author": "Christopher Greyson",
    "Tags": [
        "Fiction",
        "Crime",
        "Murder",
        "Thriller"
    ],
    "Reference": null,
    "links": [
        {
            "method": "GET",
            "uri": "http://localhost:6080/api/books/83389205-b1c9-4523-a3bb-85d7255546f9",
            "relation": "Self",
            "message": "This is a GET self link."
        },
        {
            "method": "PUT",
            "uri": "http://localhost:6080/api/books/83389205-b1c9-4523-a3bb-85d7255546f9",
            "relation": "UpdateBookById",
            "message": null
        },
        {
            "method": "DELETE",
            "uri": "http://localhost:6080/api/books/83389205-b1c9-4523-a3bb-85d7255546f9",
            "relation": "DeleteBookById",
            "message": null
        },
        {
            "method": "POST",
            "uri": "http://localhost:6080/api/books/83389205-b1c9-4523-a3bb-85d7255546f9",
            "relation": "Edit",
            "message": "Edits resource"
        },
        {
            "method": "POST",
            "uri": "http://localhost:6080/change/resource/state/%3fid=83389205-b1c9-4523-a3bb-85d7255546f9",
            "relation": "ChangeResourceState",
            "message": "Any operation in your resource."
        },
        {
            "method": "GET",
            "uri": "https://my-domain.com/api/books/83389205-b1c9-4523-a3bb-85d7255546f9",
            "relation": "Custom Domain External Link",
            "message": null
        },
        {
            "method": "GET",
            "uri": "https://google.com/search?q=The Girl Beneath the Sea (Underwater Investigation Unit Book 1)",
            "relation": "Google Search External Links",
            "message": "This will do a search on Google engine."
        }
    ]
}