RestEasy is primarily to help facilitate the implementation of RESTful CRUD API endpoints for your domain. It uses conventions and attributes to automatically generate the boilerplate "plumbing" required for APIs.
You focus on your business domain and the framework takes care of the API endpoints, serialisation etc.

• RESTful hypermedia
• Resource collections with pagination, filtering and sorting
• MultiTenancy
• Granular Authorisation
• Entity Framework integration
• OpenApi (Swagger) document generation
• Integration Testing infrastructure
• CQRS abstraction with MediatR enabling alternate non-HTTP inputs e.g. messaging, CLI apps
• Correlation
• Concurrency via ETag related headers

On top of that the library also provides functionality which can be used for general purpose .NET systems:

• Domain Driven Design objects - Entities, strongly typed Entity Ids, Aggregate Roots/Members, Value Objects etc.
• Simple bespoke database migration mechanism for Entity Framework allowing handcrafted SQL Scripts to be applied via an API endpoint (removing the need to rely on EF to script your database)
• JSON and EF Converters for DateOnly/TimeOnly types (missing from .NET Core at the time of writing)
• Extensions to the Synonms.Functional library for Railway Oriented Programming
• Paginated Lists, Date Providers, various extension methods...

Documentation is available on my Portfolio.

Shared functionality not specific to web APIs, including DDD objects, the resource schema and serialisation.

Persistence implementations for Entity Framework including a base DbContext with all of the DDD objects and domain event plumbing configured.

Web API related functionality including endpoint generation, middleware, Hypermedia and MediatR/Swashbuckle integrations.

Infrastructure to simplify Integration testing for RestEasy endpoints with test fixture base classes.

Additional test fixtures for Entity Framework integrations.

Add a reference to the Synonms.RestEasy.WebApi NuGet package.

RESTEasy requires implementations of Product, Tenant and User models. There is Middleware plumbed into the pipeline which will try to resolve each of these entities if available. They can be empty implementations as demonstrated below if you have no need for them, or you can add whatever properties you want:

public class SampleProduct : RestEasyProduct
{
}

public class SampleTenant : RestEasyTenant
{
}

public class SampleUser : RestEasyUser
{
}

RESTEasy also requires corresponding repositories for these models. Again, they can be empty implementations if you do not have any need for these items, otherwise grab them from your tenants database or call another service or whatever you want:

public class SampleProductRepository : IProductRepository<SampleProduct>
{
    public Task<IEnumerable<SampleProduct>> FindAvailableProductsAsync(CancellationToken cancellationToken) =>
        Task.FromResult(Enumerable.Empty<SampleProduct>());

    public Task<Maybe<SampleProduct>> FindSelectedProductAsync(Guid id, CancellationToken cancellationToken) =>
        Task.FromResult(Maybe<SampleProduct>.None);
}

public class SampleTenantRepository : ITenantRepository<SampleTenant>
{
    public Task<IEnumerable<SampleTenant>> FindAvailableTenantsAsync(CancellationToken cancellationToken) =>
        Task.FromResult(Enumerable.Empty<SampleTenant>());

    public Task<Maybe<SampleTenant>> FindSelectedTenantAsync(Guid id, CancellationToken cancellationToken) =>
        Task.FromResult(Maybe<SampleTenant>.None);
}

public class SampleUserRepository : IUserRepository<SampleUser>
{
    public Task<Maybe<SampleUser>> FindAuthenticatedUserAsync(CancellationToken cancellationToken) =>
        Task.FromResult(Maybe<SampleUser>.Some(new SampleUser()));
}

Finally, if you want to use lookups you need an implementation of ILookupIOptionsProvider to get lookup values (for example from a database):

public class LookupOptionsProvider : ILookupOptionsProvider
{
    public IEnumerable<FormFieldOption> Get(string discriminator) =>
        Enumerable<FormFieldOption>.Empty();
}

In Program.cs (or wherever you manage your startup code) wire up RestEasy with the classes you created:

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

ILoggerFactory loggerFactory = new LoggerFactory();

RestEasyOptions options = new()
{
    Assemblies = typeof(Program).Assembly,
    MvcOptionsConfigurationAction = mvcOptions => mvcOptions.ClearFormatters().WithDefaultFormatters(loggerFactory).WithIonFormatters(loggerFactory),
    SwaggerGenConfigurationAction = swaggerGenOptions => swaggerGenOptions.SwaggerDoc("v1.0", new OpenApiInfo { Title = "RestEasy Sample API", Version = "v1.0" }),
    SwaggerUiConfigurationAction = swaggerUiOptions => swaggerUiOptions.SwaggerEndpoint("/swagger/v1.0/swagger.json", "v1.0")
};

builder.Services.AddRestEasyFramework<SampleUser, SampleProduct, SampleTenant>(options);
builder.Services.AddSingleton<ILookupOptionsProvider, LookupOptionsProvider>();

WebApplication app = builder.Build();

app.UseRestEasyFramework<SampleUser, SampleProduct, SampleTenant>(options);

app.Run();

RestEasyOptions is the place to look if you want to customise the behaviour.

There are a few fundamental objects you will need to create at a minimum in order to achieve a functioning API:

• An Aggregate Root (the internal domain model)
• A Resource (the external presentation of your domain model)
• An Aggregate Creator (given a new Resource from the outside world, how do you validate it and create a new Aggregate Root)
• An Aggregate Updater (given an updated Resource from the outside world, how do you validate it and update the corresponding existing Aggregate Root)

Additionally, you will also likely have a Repository per Aggregate (how does the framework retrieve and store the domain models).

Aggregates are the internal representation of your domain entities. They are hierarchical groupings of data. The 'parent' object is the Aggregate Root and all 'child' objects are Aggregate Members. All actions are performed via the Aggregate Root. Repositories, for example are only available for Aggregate Roots. API endpoints are only generated for Aggregate Roots.

Unlike a database schema where all of the tables could be related, Aggregates should be as small as possible. As a rule of thumb, only that data which is necessary in order to create an Aggregate Root forms the Aggregate.

As an example, consider Employees, Employment Details and Employment Contracts as per the Sample API.
Employees have a 1-1 relationship with Employment Details which are essentially a horizontal partition of an Employee. You can't create an Employee without knowing their Employment Details and Employment Details have limited value outside the scope of an Employee. As such, we have an Aggregate with Employee as the Aggregate Root and Employment Details as an Aggregate Member.
Although Contracts have a required relationship to an Employee, Employees can be created without entering their Contract details and there is value in being able to manage Contracts independently of the Employee. As such we have another Aggregate with Contract as the Aggregate Root. Other entities which are fundamental parts of a Contract would be Aggregate Members of that Aggregate (for example if we had a separate Salary entity). API endpoints (and Repositories etc.) will be available for Employees and Contracts, but not for Employment Details. They will be updated via the Employee.

Resources are the external representation of the entities. For the most part, resources should consist of properties with simple vanilla C# types (string, int, bool etc.). Where the corresponding type on the Aggregate is a ValueObject then the Resource would present the underlying type. However, there are certain property types in Resources which will trigger special behaviour which allow for related data to be presented either as embedded data or as a link.

The default Resource mapper enumerates each public instance property on the Resource and reacts to the following special types:

All other types are assumed to be vanilla properties and Reflection is used to set the property using the value from the Aggregate. This will potentially fail if the types differ.

POST methods are used to create new Aggregates and accept the corresponding Resource in the request body. The AggregateCreator is responsible for taking the incoming Resource, validating it and creating the new Aggregate.

Use the related IAggregateRepository to check for duplicates etc. Note that the framework will automatically perform the insert and save via the implementation of the repository.

public class PermissionCreator : IAggregateCreator<Permission, PermissionResource>
{
    private readonly IAggregateRepository<Permission> _aggregateRepository;

    public PermissionCreator(IAggregateRepository<Permission> aggregateRepository)
    {
        _aggregateRepository = aggregateRepository;
    }

    public async Task<Result<Permission>> CreateAsync(PermissionResource resource, CancellationToken cancellationToken)
    {
        Maybe<Permission> existingPermissionOutcome = await _aggregateRepository.FindAsync((EntityId<Permission>)resource.Id, cancellationToken);

        return existingPermissionOutcome.Match(
        existingPermission => new DomainRuleFault("{entityType} Id '{id}' already exists.", nameof(Permission), resource.Id),
            () => Permission.Create(resource));
    }
}

PUT methods are used to update existing Aggregates and accept the corresponding Resource in the request body (the Id is obtained from the route). The AggregateUpdater is responsible for retrieving the existing Aggregate, validating the incoming Resource and updating the Aggregate.

Note that the framework will automatically find the existing aggregate and do the update and save via the implementation of the repository.

public class PermissionUpdater : IAggregateUpdater<Permission, PermissionResource>
{
    public Task<Maybe<Fault>> UpdateAsync(Permission aggregateRoot, PermissionResource resource, CancellationToken cancellationToken) =>
        Task.FromResult(aggregateRoot.Update(resource));
}

Aggregates require a Repository in order for RESTEasy to be able to store and retrieve them. The Synonms.RestEasy.EntityFramework package provides a default implementation which will do all of the work for you in most cases. Simply create a Repository class for your Aggregate and inherit from AggregateRepository:

public class PermissionRepository : AggregateRepository<Permission>
{
    public PermissionRepository(MyDbContext dbContext) : base(dbContext)
    {
    }
}

There will be cases when you need to specify Include clauses when surfacing your resources to pull in aggregate members etc. To do that, simply override the virtual members:

public class RoleRepository : AggregateRepository<Role>
{
    public RoleRepository(MyDbContext dbContext) : base(dbContext)
    {
    }

    public override async Task<Maybe<Role>> FindAsync(EntityId<Role> id, CancellationToken cancellationToken)
    {
        Role? aggregateRoot = await DbContext.Set<Role>()
            .Include(role => role.Product)
            .Include(role => role.RolePermissions).ThenInclude(rolePermission => rolePermission.Permission)
            .FirstOrDefaultAsync(role => role.Id == id, cancellationToken);

        return aggregateRoot ?? Maybe<Role>.None;
    }

    public override IQueryable<Role> Query(Expression<Func<Role, bool>> predicate) =>
        DbContext.Set<Role>()
            .Include(role => role.Product)
            .Include(role => role.RolePermissions).ThenInclude(rolePermission => rolePermission.Permission)
            .Where(predicate);

    public override Task<PaginatedList<Role>> ReadAllAsync(int offset, int limit, Func<IQueryable<Role>, IQueryable<Role>> sortFunc, CancellationToken cancellationToken)
    {
        IIncludableQueryable<Role, Permission> queryable = DbContext.Set<Role>()
            .Include(role => role.Product)
            .Include(role => role.RolePermissions).ThenInclude(rolePermission => rolePermission.Permission);

        return Task.FromResult(PaginatedList<Role>.Create(sortFunc.Invoke(queryable), offset, limit));
    }
}

For all of this to work you will of course need a DbContext. There is a base class for that too which wires in all the value converters you need and adds Domain Event capabilities too.

public class MyDbContext : RestEasyDbContext
{
    public MyDbContext(DbContextOptions<MyDbContext> options, IDomainEventDispatcher domainEventDispatcher)
        : base(options, domainEventDispatcher)
    {
    }

    protected MyDbContext(DbContextOptions options, IDomainEventDispatcher domainEventDispatcher)
        : base(options, domainEventDispatcher)
    {
    }

    // Add whatever DbSets you want as normal
    public DbSet<Permission> PermissionDbSet { get; set; } = null!;

    protected override void ConfigureConventions(ModelConfigurationBuilder configurationBuilder)
    {
        base.ConfigureConventions(configurationBuilder);

        RegisterValueTypeValueConverters(configurationBuilder, MyWebApiProject.Assembly);
    }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.ApplyConfigurationsFromAssembly(EntityFrameworkCoreProject.Assembly);
        modelBuilder.ApplyConfigurationsFromAssembly(MyWebApiProject.Assembly);

        RegisterEntityIdValueConverters(modelBuilder);
    }
}

Add it to your DI container:

serviceCollection.AddScoped(serviceProvider =>
{
    IDomainEventDispatcher domainEventDispatcher = serviceProvider.GetRequiredService<IDomainEventDispatcher>();

    string? connectionString = configuration.GetConnectionString("MyConnectionString");

    if (string.IsNullOrWhiteSpace(connectionString))
    {
        throw new ApplicationException("Unable to determine valid connection string from configuration.");
    }

    DbContextOptions<MyDbContext> options = new DbContextOptionsBuilder<MyDbContext>()
        .UseSqlServer(connectionString, options => options.EnableRetryOnFailure())
        .Options;
    MyDbContext myDbContext = new(options, domainEventDispatcher);

    return myDbContext;
});

// RestEasyDbContext is used by the framework for Migrations
serviceCollection.AddScoped<RestEasyDbContext>(serviceProvider => serviceProvider.GetRequiredService<MyDbContext>());

If you are averse to Entity Framework you can by all means provide your own implementations of IAggregateRepository, it's just obviously more work.

By default the full range of CRUD endpoints are available:

Generation of the endpoints is triggered by the RestEasyResourceAttribute decorating a domain model:

[RestEasyResource(typeof(EmployeeResource), "employees", requiresAuthentication: false, pageLimit: 5)]
public class Employee : AggregateRoot<Employee>
{
  ...
}

The parameters provided to the attribute influence how the endpoints are generated:

RestEasy supports OpenApi documentation and documents the paths/operations for all generated endpoints. No action is required other than enabling Swashbuckle at startup.

builder.Services.AddRestEasyFramework(mvcOptions => mvcOptions.WithDefaultFormatters().WithIonFormatters(), SampleApiProject.Assembly)
    .WithApplicationDependenciesFrom(SampleApiProject.Assembly)
    .WithDomainDependenciesFrom(SampleApiProject.Assembly)
    .WithOpenApi(swaggerGenOptions =>
    {
        swaggerGenOptions.SwaggerDoc("v1.0", new OpenApiInfo { Title = "RestEasy Sample API", Version = "v1.0" });
    });

RestEasy initially supports JSON (application/json) and ION Hypermedia (application/ion+json) content types.

The default JSON format is lightly decorated to accommodate self links and pagination data. Otherwise it is "vanilla" JSON. It is recommended for clients which do not require RESTful Hypermedia, for example back-end data services.

The ION format is richly decorated with Hypermedia and is recommended for clients who want the self describing capabilities of a RESTful service (for example a dynamic, link driven UI).

Examples follow to help visualise the difference.

Default JSON format:

{
  "value": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "title": "Mr",
      "forename": "Kendrick",
      "surname": "Lamar",
      // ...other properties...
    },
    // ...other resources...
  ],
  "self": {
    "href": "https://localhost:5001/employees",
    "rel": "self",
    "method": "GET"
  },
  "offset": 0,
  "limit": 5,
  "size": 9
}

ION Format:

{
    "value": [
        {
            "id": "00000000-0000-0000-0000-000000000001",
            "title": "Mr",
            "forename": "Kendrick",
            "surname": "Lamar",
            //...other properties...,
            "self": {
                "href": "https://localhost:5001/employees/00000000-0000-0000-0000-000000000001",
                "rel": "self",
                "method": "GET"
            },
            "edit-form": {
                "href": "https://localhost:5001/employees/00000000-0000-0000-0000-000000000001/edit-form",
                "rel": "edit-form",
                "method": "GET"
            },
            "delete": {
                "href": "https://localhost:5001/employees/00000000-0000-0000-0000-000000000001",
                "rel": "self",
                "method": "DELETE"
            },
            "homeAddress": {
                "href": "https://localhost:5001/addresses/00000000-0000-0000-0001-000000000001",
                "rel": "related",
                "method": "GET"
            },
            "contracts": {
                "href": "https://localhost:5001/contracts?employeeId=00000000-0000-0000-0000-000000000001",
                "rel": "related",
                "method": "GET"
            }
        },
        // ...other resources...
    ],
    "self": {
        "href": "https://localhost:5001/employees",
        "rel": "self",
        "method": "GET"
    },
    "create-form": {
        "href": "https://localhost:5001/employees/create-form",
        "rel": "create-form",
        "method": "GET"
    },
    "offset": 0,
    "limit": 5,
    "size": 9,
    "first": {
        "href": "https://localhost:5001/employees?offset=0",
        "rel": "collection",
        "method": "GET"
    },
    "last": {
        "href": "https://localhost:5001/employees?offset=5",
        "rel": "collection",
        "method": "GET"
    },
    "next": {
        "href": "https://localhost:5001/employees?offset=5",
        "rel": "collection",
        "method": "GET"
    }
}

Additional formats can be supported by creating a suite of JsonConverters in WebApi/Serialisation and Formatters in WebApi/Hypermedia. The OpenApi operations will also need to be tweaked in the RestEasyDocumentFilter class for the new media type to be reflected in the OpenApi documentation.

Client faults handled by the framework are presented back to the client as an array of errors:

{
  "errors": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "code": "VAL01",
      "title": "Validation Rule",
      "detail": "Name must be 20 characters or less.",
      "source": {
        "pointer": "Name",
        "parameter": "Ienteredanunacceptablylongname"
      }
    }
  ],
  "self": {
    "href": "https://localhost:5001/employees",
    "rel": "self",
    "method": "POST"
  }
}

Client faults resolve to the following HTTP response codes:

Any other type of fault is considered a server fault and will present back to the client as a 500 Internal Server Error without a response body.

Anti-corruption layer validation failures (e.g. Name is not filled in) should be surfaced as an ApplicationRulesFault. Business logic validation failures (e.g. ContractStartDate must be on or after the EmploymentStartDate) should be surfaced as a DomainRulesFault. The AggregateRules class is designed to simplify the implementation of domain rules and generation of validation failures:

internal static Result<Legislation> Create(LegislationResource resource) =>
    AggregateRules.CreateBuilder()
        .WithMandatoryValueObject(resource.Name, x => Moniker.CreateMandatory(x, NameMaxLength), out Moniker nameValueObject)
        .WithDomainRules(
            RelatedEntityIdRuleset<Lookup>.Create(nameof(CurrencyId), resource.CurrencyId)
            )
        .Build()
        .ToResult(() => new Legislation((EntityId<Legislation>)resource.Id, nameValueObject, resource.CurrencyId));

In the above example the WithMandatoryValueObject call performs the conversion of plain string type to Moniker ValueObject (including validating it). The WithDomainRules call allows you to pass a collection of IDomainRuleset implementations. In this case we're just checking the CurrencyId is not an empty Guid but you can make whatever rulesets you want. Any validation failures will be aggregated and passed back to the caller as a DomainRulesFault. Only if no faults occur will the Legislation be created.

EntityNotFoundFault should be used when one of the resources specified in the route is not found. If some related required entity is not found which does not form part of the route then an alternative Fault type should be used.