MasLazu.AspNet.Authorization.Core.Endpoint 1.0.0-preview.1

MasLazu.AspNet.Authorization.Core.Endpoint

This project provides the HTTP API endpoints for the MasLazu ASP.NET Authorization system using FastEndpoints. It exposes RESTful APIs for managing authorization entities such as actions, permissions, resources, and their relationships.

Overview

The Endpoint layer serves as the HTTP interface for the authorization system, providing RESTful APIs that allow clients to perform CRUD operations on authorization entities. Built on FastEndpoints, it offers high performance, type safety, and excellent developer experience.

Architecture

Endpoint Layer
├── Endpoints/         # Individual endpoint implementations
│   ├── Actions/
│   ├── Permissions/
│   ├── PermissionTypes/
│   ├── Resources/
│   └── ResourceActions/
├── EndpointGroups/    # Route grouping and configuration
└── Extensions/        # Dependency injection setup

Endpoints

Each entity type has a consistent set of endpoints:

Actions Endpoints

• GET /v1/actions/{id} - Get action by ID
• POST /v1/actions/paginated - Get paginated actions

Permissions Endpoints

• GET /v1/permissions/{id} - Get permission by ID
• POST /v1/permissions/paginated - Get paginated permissions

PermissionTypes Endpoints

• GET /v1/permission-types/{id} - Get permission type by ID
• POST /v1/permission-types/paginated - Get paginated permission types

Resources Endpoints

• GET /v1/resources/{id} - Get resource by ID
• POST /v1/resources/paginated - Get paginated resources

ResourceActions Endpoints

• GET /v1/resource-actions/{id} - Get resource action by ID
• POST /v1/resource-actions/paginated - Get paginated resource actions

Endpoint Implementation

All endpoints inherit from BaseEndpoint<TRequest, TResponse> and follow a consistent pattern:

public class GetActionByIdEndpoint : BaseEndpoint<IdRequest, ActionDto>
{
    public IActionService ActionService { get; set; }

    public override void ConfigureEndpoint()
    {
        Get("/{Id}");
        Group<ActionsEndpointGroup>();
    }

    public override async Task HandleAsync(IdRequest req, CancellationToken ct)
    {
        ActionDto result = await ActionService.GetByIdAsync(Guid.Empty, req.Id, ct) ??
            throw new NotFoundException(nameof(ActionDto), req.Id);
        await SendOkResponseAsync(result, "Action Retrieved Successfully", ct);
    }
}

Endpoint Groups

Endpoints are organized into groups for better route management:

Base Group Structure

V1EndpointGroup (base)
├── ActionsEndpointGroup (/v1/actions)
├── PermissionsEndpointGroup (/v1/permissions)
├── PermissionTypesEndpointGroup (/v1/permission-types)
├── ResourcesEndpointGroup (/v1/resources)
└── ResourceActionsEndpointGroup (/v1/resource-actions)

Group Configuration

public class ActionsEndpointGroup : SubGroup<V1EndpointGroup>
{
    public ActionsEndpointGroup()
    {
        Configure("actions", ep => ep.Description(x => x.WithTags("Actions")));
    }
}

Request/Response Patterns

Common Request Types

• IdRequest - For single entity retrieval
• PaginationRequest - For paginated results

Common Response Types

• ActionDto, PermissionDto, etc. - Individual entity responses
• PaginatedResult<TDto> - Paginated list responses

Response Format

All endpoints return standardized responses:

{
  "data": { ... },
  "message": "Operation completed successfully",
  "success": true
}

Authentication & Authorization

Current Implementation

• Most endpoints require authentication (default behavior)
• Paginated endpoints are marked AllowAnonymous() for public access
• Individual entity endpoints require authentication

Future Considerations

The framework supports adding authorization policies:

public override void ConfigureEndpoint()
{
    // Add authorization requirements
    // Policies, roles, permissions, etc.
}

Error Handling

Endpoints use consistent error handling:

• NotFoundException for missing entities
• Framework-level validation errors
• Standardized error response format

Dependencies

This project depends on:

• MasLazu.AspNet.Authorization.Core.Abstraction - Service interfaces and DTOs
• FastEndpoints - High-performance API framework
• MasLazu.AspNet.Framework.Endpoint - Base endpoint classes and utilities

Usage

Basic Setup

var builder = WebApplication.CreateBuilder(args);

// Add authorization core services
builder.Services.AddAuthorizationCoreApplication();

// Add endpoints (auto-discovered by FastEndpoints)
builder.Services.AddFastEndpoints();

var app = builder.Build();

// Map endpoints
app.UseFastEndpoints();

app.Run();

API Usage Examples

Get Action by ID

GET /v1/actions/123e4567-e89b-12d3-a456-426614174000
Authorization: Bearer {token}

Get Paginated Actions

POST /v1/actions/paginated
Content-Type: application/json

{
  "page": 1,
  "pageSize": 10,
  "sortBy": "name",
  "sortDirection": "asc"
}

Swagger/OpenAPI

Endpoints are automatically documented with:

• Route information
• Request/response schemas
• Tags for grouping
• Descriptions and summaries

Performance Features

• FastEndpoints: High-performance API framework
• Async/Await: Non-blocking I/O operations
• Dependency Injection: Efficient service resolution
• Pagination: Efficient data retrieval for large datasets

Integration

This Endpoint project integrates with:

• Abstraction Layer: Uses service interfaces and DTOs
• Core Layer: Consumes business logic services
• Client Applications: Provides HTTP API for web/mobile clients

The Endpoint layer provides a clean HTTP interface while maintaining separation of concerns with the underlying business logic.