Headless UI API Architecture

[adambarath]

Headless UI API Architecture and .NET 9.0 Upgrade

Overview

This PR introduces a major architectural refactoring of IdentityManager2, separating concerns between API and UI layers while upgrading the entire solution to .NET 9.0.

Key Changes

1. Headless UI API Layer

• Introduced IdentityManager2.Apis project: A standalone API layer that exposes identity management operations through RESTful endpoints
• Decoupled architecture: Developers can now build custom client UIs by consuming the API independently
• Comprehensive API endpoints:
  • User management (UsersController): CRUD operations, claims, and role management
  • Role management (RolesController): Role CRUD and property management
  • Metadata endpoint (MetaController): Discovery of available operations and configuration
• OpenAPI documentation: All endpoints include proper attribute decorations ([EndpointName], [EndpointSummary], [ProducesResponseType], [Tags]) for automatic API documentation generation

2. Separated UI Project

• Dedicated IdentityManager2 UI project: Contains all Razor Pages and front-end assets
• Clear separation of concerns: API logic is now independent from presentation layer
• Embedded HTML resources: UI assets remain self-contained using EmbeddedHtmlResult
• Flexible hosting: The UI can be hosted separately or alongside the API

3. .NET 9.0 Target Framework

• Upgraded all projects to .NET 9.0 (<TargetFramework>net9.0</TargetFramework>)
• C# 13.0 language features: Leveraging latest language improvements
• Updated dependencies: All NuGet packages updated to support .NET 9.0
• Modern ASP.NET Core features: Utilizing latest middleware, routing, and endpoint conventions

Benefits

✅ Flexibility: Build custom UIs (React, Angular, Blazor, mobile apps) using the headless API
✅ Maintainability: Clear separation makes both API and UI easier to maintain and test
✅ Modern stack: .NET 9.0 provides performance improvements and latest framework features
✅ API-first approach: RESTful design enables integration with any HTTP client
✅ Backward compatibility: Existing UI functionality preserved in separate project

Migration Notes

For developers upgrading from previous versions:

• The API endpoints are now available under the IdentityManager2.Apis namespace
• Configuration extension methods updated: AddIdentityManagerApi() and MapIdentityManagerApi()
• UI remains accessible through existing routing patterns when both projects are referenced

Testing

• API endpoints tested via Swagger/OpenAPI
• Existing UI functionality verified
• Sample host project (Hosts.IdentityServerAuthentication) updated and tested

---