Home

Inline configuration

Inside the ConfigureHateoas method, you can define the HATEOAS configuration for your resources. The configuration is defined by chaining Configure methods for each resource you want to configure.

For example, the following configuration sets up links for a Member resource:

using HateoasNet.DependencyInjection.Core;

public void ConfigureServices(IServiceCollection services)
{
    // other registration...

    services.ConfigureHateoas(context =>
    {
        return context.Configure<List<Member>>(members =>
        {
            members.AddLink("get-members");
            members.AddLink("invite-member");
            members.AddLink("create-member");
        })

        .Configure<Member>(member =>
        {
            member.AddLink("get-member").HasRouteData(e => new { id = e.Id });
            member.AddLink("update-member").HasRouteData(e => new { id = e.Id });
        })

        .Configure<Member>(member =>
        {
            member.AddLink("get-guild")
                .HasRouteData(e => new { id = e.GuildId })
                .When(e => e.GuildId != null);

            member.AddLink("promote-member")
                .HasRouteData(e => new { id = e.Id })
                .When(e => e.GuildId != null && !e.IsGuildMaster);

            member.AddLink("demote-member")
                .HasRouteData(e => new { id = e.Id })
                .When(e => e.GuildId != null && e.IsGuildMaster);

            member.AddLink("leave-guild")
                .HasRouteData(e => new { id = e.Id })
                .When(e => e.GuildId != null);
        });
    });

    // other registrations...
}

In this example, the configuration sets up links for the Member resource to get, update, promote or demote a member, leave or get a guild, as well as to get all members, invite or create a member.

Here's a brief explanation of the methods and properties used in the configuration example:

• ConfigureHateoas: Configures the HateoasNet package for the application.
• Configure: Configures the links for a resource.
• AddLink: Adds a new link for a resource.
• HasRouteData: Sets the route data

Separated classes configuration

By implementing the IHateoasSourceBuilder interface, you can easily define links for your resources and provide a HATEOAS API for your users. You can have different implementations in separated classes to configure your resources the way you find suitable to your project organization.

Implementation

In the example, MemberHateoasBuilder is a class that implements the IHateoasSourceBuilder interface, allowing you to define links for a Member resource. This will allow you to define links for a Member resource using the AddLink, HasRouteData and When methods:

using HateoasNet.Abstractions;

public class MemberHateoasBuilder : IHateoasSourceBuilder<Member>
{
    public void Build(IHateoasSource<Member> resource)
    {
        resource.AddLink("get-member").HasRouteData(e => new { id = e.Id });
        resource.AddLink("update-member").HasRouteData(e => new { id = e.Id });

        resource
            .AddLink("get-guild")
            .HasRouteData(e => new { id = e.GuildId })
            .When(e => e.GuildId != null);

        resource
            .AddLink("promote-member")
            .HasRouteData(e => new { id = e.Id })
            .When(e => e.GuildId != null && !e.IsGuildMaster);

        resource
            .AddLink("demote-member")
            .HasRouteData(e => new { id = e.Id })
            .When(e => e.GuildId != null && e.IsGuildMaster);

        resource.AddLink("leave-guild")
                .HasRouteData(e => new { id = e.Id })
                .When(e => e.GuildId != null);
    }
}

• Build(IHateoasSource resource): The Build method is the main method of the MemberHateoasBuilder class. It receives an instance of the IHateoasSource interface, which allows you to define links for the Member resource.
• AddLink(string rel): The AddLink method allows you to add a link to the Member resource. It receives a string parameter rel which represents the relationship of the link to the resource.
• HasRouteData(Func<T, object> routeData): The HasRouteData method allows you to specify the route data for the link. It receives a Func<T, object> parameter routeData which represents a function that returns the route data for the link.
• When(Func<T, bool> predicate): The When method allows you to specify a condition for the link to be added. It receives a Func<T, bool> parameter predicate which represents a function that returns a boolean value indicating whether the link should be added or not.

Integration

HateoasNet provides the IHateoasSourceBuilder interface for defining HATEOAS links for a particular resource type T. In the previous session, the MemberHateoasBuilder class implements IHateoasSourceBuilder, defining the links for a Member resource. The Build method of this interface adds the necessary links to the IHateoasSource object passed as an argument.

Once all IHateoasSourceBuilder objects have been defined, the next step is to apply them to your services. The ConfigureHateoas method is used to configure the HATEOAS options for a service. In the example, this method is called within the ConfigureServices method of a Startup.cs file.

using HateoasNet.DependencyInjection.Core;

public void ConfigureServices(IServiceCollection services)
{
    // other registrations...

    // setup applying map configurations from classes in separated files
    services.ConfigureHateoas(context => context
        .ApplyConfiguration(new GuildHateoasBuilder())
        .ApplyConfiguration(new ListGuildHateoasBuilder())
        .ApplyConfiguration(new MemberHateoasBuilder())
        .ApplyConfiguration(new ListMemberHateoasBuilder())
        .ApplyConfiguration(new InviteHateoasBuilder())
        .ApplyConfiguration(new InvitesHateoasBuilder()));

    // other registrations...
}

The context.ApplyConfiguration method is used to apply the IHateoasSourceBuilder objects to the HateoasConfigurationContext object. This method takes an instance of the IHateoasSourceBuilder interface and applies the links defined by it to the corresponding resource.

Configuring with Assembly Discovery

HateoasNet allows you to configure the IHateoasSourceBuilder implementations for your resources through assembly discovery. This is useful when you have a large number of resources and builders, and you want to avoid having to manually register each of them.

To use assembly discovery, you need to call the ConfigureFromAssembly method on the IHateoasContext object inside the ConfigureHateoas method in the ConfigureServices method of your Startup class.

Here's an example of how to use assembly discovery:

using HateoasNet.DependencyInjection.Core;

public void ConfigureServices(IServiceCollection services)
{
    // other registrations...

    // setup applying configurations from IHateoasSourceBuilder implementations in separated files found in a given assembly
    services.ConfigureHateoas(context => context.ConfigureFromAssembly(typeof(GuildHateoasBuilder).Assembly));

    // other registrations...
}

The ConfigureFromAssembly method takes an Assembly object that represents the assembly where your IHateoasSourceBuilder implementations are located. In the example above, we're passing in the assembly that contains the GuildHateoasBuilder class. HateoasNet will then scan the assembly for any classes that implement the IHateoasSourceBuilder interface and automatically register them.

Keep in mind that HateoasNet will only discover classes that implement the IHateoasSourceBuilder interface and have a default constructor. If you have builders that don't meet these criteria, you'll need to register them manually.

With this approach, you can avoid the need to manually register each IHateoasSourceBuilder implementation in your application like in the previous session.