CFW.EntityMinimalApi 1.0.2

Entity Minimal API

Entity Minimal API is a lightweight framework built on ASP.NET Core OData and Minimal API, fully compatible with .NET Core 8. It is designed to simplify entity management by focusing on clean, extensible handlers. Instead of manually managing HTTP status codes and request-response models, it leverages a Result Pattern to streamline operation outcomes and take advantage of the latest improvements in .NET Core 8.

Installation

Using .NET CLI:

dotnet add package EntityMinimalApi

Using Package Manager:

Install-Package EntityMinimalApi 

In the ASP.NET Core Mimimal API project, update your Program.cs as below:

var builder = WebApplication.CreateBuilder(args);

//Register your DbContext
builder.Services.AddDbContext<SampleDbContext>(
               options => options
               .ReplaceService<IModelCustomizer, AutoScanModelCustomizer<SampleDbContext>>() //Optional: Auto register entities with marker interface
               .EnableSensitiveDataLogging()
               .UseSqlite($@"Data Source=sample_db.db"));

//Add Entity Minimal API with default route prefix "odata-api"
builder.Services.AddEntityMinimalApi(o => o.UseDefaultDbContext<SampleDbContext>());

....

var app = builder.Build();

// Use Entity Minimal API
app.UseEntityMinimalApi();

Create a new ViewModel or DbModel class and add the [Entity] attribute to it. The framework will automatically generate CRUD endpoints for the entity.:

[Entity("products")]
public class Product : IEntity<int>
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
    public Category Category { get; set; }
    public IEnumerable<Order> Orders { get; set; }
}

The framework will automatically generate CRUD endpoints for the Product entity. You can customize the generated endpoints by implementing custom handlers.

Key Features

1. Common CRUD Entity API
   • GET /products or /products/{key} with OData Query Options
   • POST /products with 1-Level Nested Relationships
   • PATCH /products/{key} with Partial Updates
   • DELETE /products/{key}
2. Entity Operations
   • Function GET Non Key-Bound
   • Action POST Key-Bound
3. Unbound Operations
   • Unbound Function GET
   • Unbound Action POST
4. Authentication and Authorization
5. ViewModel Support
6. Automatic Entity Configuration

1. Common CRUD Entity API

Automatically generate CRUD endpoints (POST, GET, DELETE, PATCH) for database entities or ViewModels with minimal configuration. You can restrict generated endpoints use Methods property of EntityAttribute attribute.

Example:

[Entity("products")]
//[Entity("products", Methods = [EntityMethods.Get, EntityMethods.Post])] // Only GET and POST methods are allowed
public class Product : IEntity<int>
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
    public Category Category { get; set; }
    public IEnumerable<Order> Orders { get; set; }
}

Generated endpoints:

GET: Query and get by key with OData query options:

The following OData query options are supported for both:

• GET /products: Retrieve a list of all products with query capabilities.
• GET /products/{id}: Retrieve a specific product by ID with additional query capabilities.

POST /products with 1-Level nested relationships:

The framework supports creating:

1. Main Entity: Insert a single entity into the database.
2. Child Entities (1 Level Nested): Handle child entities (either a single complex entity or a collection of entities) nested directly under the main entity.
   • Existing Child Entities: If the child item's ID exists in the database, it is ignored.
   • New Child Entities: If the child item's ID is null or not in the database, it is inserted.

PATCH /products/{id} with partial updates:

The PATCH method supports updating specific fields of an existing <strong>ROOT</strong> entity. The request body should contain only the fields that need to be updated.

DELETE /products/{id}:

2. Entity operations

• Function: Defines custom read-only operations bound to an entity or entity set. Functions do not modify the state of the data and are invoked via GET requests.
• Action: Defines custom operations bound to an entity or entity set. Actions can modify the state of the data and are invoked via POST requests.

Function GET non key-bound entity set:

public class GetDiscountedProducts
{
    public class Request
    {
        public decimal MaxPrice { get; set; }
        public int MaxDiscount { get; set; }
    }
    public class Response
    {
        public IEnumerable<Product> Products { get; set; }
    }

    //URL: GET /products/getDiscountedProducts?maxPrice=100&maxDiscount=20
    [EntityFunction("getDiscountedProducts")]
    public class Handler : IEntityOperationHandler<Product, Request, Response>
    {
        public Task<Result<Response>> Handle(Request request, CancellationToken cancellationToken)
        {
            /// Your logic here
        }
    }
}

Function GET key-bound entity:

public class GetProductDetails
{
    public class Request
    {
        [FromRoute] //or [Key]
        public int ProductId { get; set; }
        public bool IncludeOrders { get; set; }
    }

    public class Response
    {
        public IEnumerable<Product> Products { get; set; }
    }

    // URL: GET /products/{id}/getProductDetails?includeOrders=true
    [EntityFunction("getProductDetails")]
    public class Handler : IEntityOperationHandler<Product, Request, Response>
    {
        public Task<Result<Response>> Handle(Request request, CancellationToken cancellationToken)
        {
            /// Your logic here
        }
    }
}

Action POST non key-bound entity set:

public class AddProduct
{
    public class Request
    {
        public string Name { get; set; }
        public decimal Price { get; set; }
    }

    public class Response
    {
        public Product Product { get; set; }
    }

    //URL: POST /products/addProduct with request json body: { "name": "Product A", "price": 150.0 }
    [EntityAction("addProduct")]
    public class Handler : IEntityOperationHandler<Product, Request, Response>
    {
        public Task<Result<Response>> Handle(Request request, CancellationToken cancellationToken)
        {
            /// Your logic here
        }
    }
}

Action POST key-bound entity:

public class AddOrder
{
    public class Request
    {
        [FromRoute] //or [Key]
        public int ProductId { get; set; }

        public string OrderNumber { get; set; }
    }

    public class Response
    {
        public Order Order { get; set; }
    }

    //URL: POST /products/{id}/addOrder with request json body: { "orderNumber": "Order 1" }
    [EntityAction("addOrder")]
    public class Handler : IEntityOperationHandler<Product, Request, Response>
    {
        public Task<Result<Response>> Handle(Request request, CancellationToken cancellationToken)
        {
            /// Your logic here
        }
    }
}

Action POST non key-bound entity with no response

public class DeleteAllOrders
{
    public class Request
    {
        public int ProductId { get; set; }
    }

    //URL: POST /products/deleteAllOrders with request json body: { "productId": 1 }
    [EntityAction("deleteAllOrders")]
    public class Handler : IEntityOperationHandler<Product, Request>
    {
        public Task<Result> Handle(Request request, CancellationToken cancellationToken)
        {
            /// Your logic here
        }
    }
}

Action POST key-bound entity with no response

public class DeleteOrder
{
    public class Request
    {
        [FromRoute] //or [Key]
        public int ProductId { get; set; }
        public int OrderId { get; set; }
    }

    //URL: POST /products/{id}/deleteOrder with request json body: { "orderId": 1 }
    [EntityAction("deleteOrder")]
    public class Handler : IEntityOperationHandler<Product, Request>
    {
        public Task<Result> Handle(Request request, CancellationToken cancellationToken)
        {
            /// Your logic here
        }
    }
}

3. Unbound operations

• Unbound function: Defines custom read-only operations that are not bound to any entity or entity set. Functions do not modify the state of the data and are invoked via GET requests.
• Unbound action: Defines custom operations that are not bound to any entity or entity set. Actions can modify the state of the data and are invoked via POST requests.

Unbound Function GET with non key-bound entity set:

public class GetProductsWithDiscount
{
    public class Request
    {
        public decimal MaxPrice { get; set; }
        public int MaxDiscount { get; set; }
    }

    public class Response
    {
        public IEnumerable<Product> Products { get; set; }
    }

    //URL: GET /getProductsWithDiscount?maxPrice=100&maxDiscount=20
    [UnboundFunction("getProductsWithDiscount")]
    public class Handler : IUnboundOperationHandler<Request, Response>
    {
        public Task<Result<Response>> Handle(Request request, CancellationToken cancellationToken)
        {
            /// Your logic here
        }
    }
}

Unbound Function GET with key-bound entity:

public class GetProductDetails
{
    public class Request
    {
        [FromRoute] //or [Key]
        public int ProductId { get; set; }
        public bool IncludeOrders { get; set; }
    }

    public class Response
    {
        public IEnumerable<Product> Products { get; set; }
    }

    // URL: GET /getProductDetails/{id}?includeOrders=true
    [UnboundFunction("getProductDetails")]
    public class Handler : IUnboundOperationHandler<Request, Response>
    {
        public Task<Result<Response>> Handle(Request request, CancellationToken cancellationToken)
        {
            /// Your logic here
        }
    }
}

Unbound Action POST with non key-bound entity set:

public class AddProduct
{
    public class Request
    {
        public string Name { get; set; }
        public decimal Price { get; set; }
    }

    public class Response
    {
        public Product Product { get; set; }
    }

    //URL: POST /addProduct with request json body: { "name": "Product A", "price": 150.0 }
    [UnboundAction("addProduct")]
    public class Handler : IUnboundOperationHandler<Request, Response>
    {
        public Task<Result<Response>> Handle(Request request, CancellationToken cancellationToken)
        {
            /// Your logic here
        }
    }
}

Unbound Action POST with key-bound entity:

public class AddOrder
{
    public class Request
    {
        [FromRoute] //or [Key]
        public int ProductId { get; set; }

        public string OrderNumber { get; set; }
    }

    public class Response
    {
        public Order Order { get; set; }
    }

    //URL: POST /addOrder/{id} with request json body: { "orderNumber": "Order 1" }
    [UnboundAction("addOrder")]
    public class Handler : IUnboundOperationHandler<Request, Response>
    {
        public Task<Result<Response>> Handle(Request request, CancellationToken cancellationToken)
        {
            /// Your logic here
        }
    }
}

Unbound Action POST with no response

public class DeleteAllOrders
{
    public class Request
    {
        public int ProductId { get; set; }
    }

    //URL: POST /deleteAllOrders with request json body: { "productId": 1 }
    [UnboundAction("deleteAllOrders")]
    public class Handler : IUnboundOperationHandler<Request>
    {
        public Task<Result> Handle(Request request, CancellationToken cancellationToken)
        {
            /// Your logic here
        }
    }
}

Unbound Action POST with no response and key-bound entity:

public class DeleteOrder
{
    public class Request
    {
        [FromRoute] //or [Key]
        public int ProductId { get; set; }
        public int OrderId { get; set; }
    }

    //URL: POST /deleteOrder/{id} with request json body: { "orderId": 1 }
    [UnboundAction("deleteOrder")]
    public class Handler : IUnboundOperationHandler<Request>
    {
        public Task<Result> Handle(Request request, CancellationToken cancellationToken)
        {
            /// Your logic here
        }
    }
}

4. Authentication and Authorization

The framework integrates seamlessly with ASP.NET Core's authentication and authorization mechanisms to provide secure access to entities and operations. This includes:

1. Authentication: Ensures that only authenticated users can access the application.
2. Authorization: Enforces role-based and method-specific access control, leveraging:
   • EntityAuthorize: Custom attribute for CRUD operations, inheriting from ASP.NET Core's AuthorizeAttribute.
   • ASP.NET Core's AuthorizeAttribute: Used for custom entity operations.

By following the ASP.NET Core model, the framework ensures compatibility with existing security configurations, such as JwtBearer, CookieAuthentication, or external providers (e.g., OAuth, OpenID Connect).

Example: Configuring Authorization for an Entity

[Entity("multi-authorizations")]
[EntityAuthorize(ApplyMethods = new[] { EntityMethod.Query })] // Only authorized users can query the entity.
[EntityAuthorize(ApplyMethods = new[] { EntityMethod.GetByKey }, Roles = TestUtils.AdminRole)] // Admin-only access for GetByKey.
[EntityAuthorize(ApplyMethods = new[] { EntityMethod.Post }, Roles = $"{TestUtils.AdminRole},{TestUtils.SupperAdminRole}")] // Admin and SuperAdmin access for Post.
[EntityAuthorize(ApplyMethods = new[] { EntityMethod.Delete }, Roles = TestUtils.SupperAdminRole)] // SuperAdmin-only access for Delete.
public class MultiAuthorization : IEntity<Guid>
{
    public Guid Id { get; set; }
}

Example: Configuring Authorization for an Entity Operation

public class DeleteAllOrders
{
    public class Request
    {
        public int ProductId { get; set; }
    }

    [Authorzie(Roles = TestUtils.AdminRole)] // Only Admin can access this action.
    [UnboundAction("deleteAllOrders")]
    public class Handler : IUnboundOperationHandler<Request>
    {
        public Task<Result> Handle(Request request, CancellationToken cancellationToken)
        {
            /// Your logic here
        }
    }
}

5. View model support

The framework provides basic support for mapping between ViewModels and DbModels. The generated SQL query behavior remains the same, but the response is mapped to the ViewModel.

1. Automatic Mapping:
   • If the ViewModel and DbModel have the same type and property names, the mapping is handled automatically.
2. Custom Mapping:
   • If property names differ, the EntityPropertyNameAttribute can be used to specify the mapping explicitly.

DbModel:

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
}

ViewModel:

[Entity("products", DbSetType = typeof(Product))]
public class ProductViewModel
{
    public int Id { get; set; }
    [EntityPropertyName("Name")]
    public string ProductName { get; set; }
    public decimal Price { get; set; }
}

6. Automatic Entity Configuration

The framework simplifies entity configuration by automatically adding database entities to the DbContext using a marker interface. This eliminates the need to manually register entities in the DbContext class.

Example:

//Change the marker interface to your own interface if needed, if you use built-in IEntity<> interface, you don't need to set this property.
AutoScanModelCustomizer<SampleDbContext>.EntityMarkerTypes = new[]
{
    typeof(IEntity<>)
};

builder.Services.AddDbContext<SampleDbContext>(
               options => options
               .ReplaceService<IModelCustomizer, AutoScanModelCustomizer<SampleDbContext>>()
               .EnableSensitiveDataLogging()
               .UseSqlite($@"Data Source=sample_db.db"));