Sciensoft.Hateoas

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 a first-class citizen, so your configuration starts with a lambda expression. This library DO NOT enforce REST constraints or Richardson Maturity Level, and this has to be done by you, Sciensoft.Hateoas helps you only with the implementation of HATEOAS in your resource.

Learn more about RESTful API here and Lambda Expressions here.

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"
    ],
    "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"
        },
        {
            "method": "DELETE",
            "uri": "http://localhost:6080/api/books/83389205-b1c9-4523-a3bb-85d7255546f9",
            "relation": "DeleteBookById"
        },
        {
            "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/?id=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"
        },
        {
            "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."
        }
    ]
}

Features

Collections result with links,
Json.NET and System.Text.Json settings support,
Self-link generation,
Named Route link generation,
Custom link generation with support to path override,
External links configuration,
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.

Contributions

Before start contributing, check our CONTRIBUTING guideline out, also, before doing any significant change, have a look at the existing Issues and Pull Requests, one of them may be tackling the same thing.

Issues

To open an issue or even suggest a new feature, please use the Issues tab.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.

AlexzSouz / Sciensoft.Hateoas