Skip to content

api.md

Latest commit

 

History

History
167 lines (140 loc) · 6.19 KB

api.md

File metadata and controls

167 lines (140 loc) · 6.19 KB

API Component Documentation

Scope

The API project is in src/LearningBank.Api and exposes the My Learning Bank backend as ASP.NET Core minimal API endpoints under /api/v1.

Responsibilities

  • Authenticate and authorize requests using JWT bearer authentication and role-based policies.
  • Enforce role and parent-child link constraints at endpoint boundaries.
  • Validate incoming payloads with FluentValidation.
  • Delegate business invariants to the domain layer.
  • Persist state through repository abstractions implemented by infrastructure.
  • Emit audit log entries for administrative actions.

Runtime and Startup

  • Entry point: src/LearningBank.Api/Program.cs
  • Environment configuration: src/LearningBank.Api/appsettings.json and appsettings.Development.json
  • Infrastructure registration: AddInfrastructure from LearningBank.Infrastructure

Startup pipeline includes:

  1. Serilog configuration
  2. EF Core and repository DI via AddInfrastructure
  3. Multi-scheme JWT authentication (Google and Microsoft) selected by PolicyScheme
  4. Claims transformation for user bootstrap and role claim augmentation
  5. Authorization policies Parent, Child, and PlatformAdmin
  6. FluentValidation registration
  7. CORS for frontend origin
  8. Global fixed-window rate limiting (100 requests per minute key partition)
  9. Route registration under /api/v1

Authentication and Authorization

Authentication:

  • Policy scheme: MultiProviderJwt chooses GoogleJwt or MicrosoftJwt by token issuer
  • Google authority and issuers come from Auth:GoogleAuthority and Auth:Google:ValidIssuers
  • Microsoft authority and issuer validation come from Auth:MicrosoftAuthority, Auth:Microsoft:ValidIssuers, and IsAllowedMicrosoftIssuer
  • Audiences come from Auth:Google:Audience and Auth:Microsoft:Audience

Authorization policies:

  • Parent policy: requires role Parent
  • Child policy: requires role Child
  • PlatformAdmin policy: requires role PlatformAdmin

Helper extensions live in src/LearningBank.Api/Auth/AuthHelpers.cs and are used to extract user identity and role from claims. PlatformAdmin role assignment is applied in LearningBankClaimsTransformer using Auth:PlatformAdmin allow-lists.

Endpoint Groups

Registered route group: /api/v1

User Endpoints

File: src/LearningBank.Api/Endpoints/UserEndpoints.cs

  • GET /me
  • GET /children
  • POST /children
  • GET /parents/admins
  • POST /parents/admins

Behavior notes:

  • Create child records a Child user and a ChildLink to the parent.
  • Child creation writes an audit record.
  • Parent co-admin creation is guarded by runtime configuration (AllowParentCoAdmins).

Admin Endpoints

File: src/LearningBank.Api/Endpoints/AdminEndpoints.cs

  • GET /admin/users
  • PATCH /admin/users/{userId}
  • DELETE /admin/users/{userId}
  • GET /admin/health
  • GET /admin/settings
  • PUT /admin/settings

Behavior notes:

  • All routes require PlatformAdmin policy.
  • User listing supports query filtering and grouped family hierarchies.
  • User deletion is blocked unless runtime setting AllowUserDeletion is enabled.
  • Runtime settings updates are audited.

Category Endpoints

File: src/LearningBank.Api/Endpoints/CategoryEndpoints.cs

  • GET /categories
  • POST /categories
  • PUT /categories/{id}
  • POST /categories/{id}/archive
  • POST /categories/{id}/unarchive

Behavior notes:

  • Parent sees all categories, child sees active child-allowed categories.
  • Mutating category actions write audit records.

Account Endpoints

File: src/LearningBank.Api/Endpoints/AccountEndpoints.cs

  • GET /children/{childId}/accounts/checking
  • GET /children/{childId}/accounts/savings

Behavior notes:

  • Child can only view own data.
  • Parent can only view linked children.
  • Balance is derived from transaction sums, never stored.

Transaction and Transfer Endpoints

File: src/LearningBank.Api/Endpoints/TransactionEndpoints.cs

  • POST /deposits
  • POST /withdrawals
  • DELETE /transactions/{transactionId}
  • POST /transfers/checking-to-savings
  • POST /transfers/savings-to-checking
  • GET /transfers/requests/pending
  • GET /children/{childId}/transfers/requests
  • POST /transfers/requests/{requestId}/review
  • DELETE /transfers/requests/{requestId}

Behavior notes:

  • Deposits validate category availability at submission time.
  • Withdrawal is parent-only and audited.
  • Checking to savings uses AccountService atomic pair creation with insufficient funds guard.
  • Savings to checking is request based and requires parent review.
  • Approval/rejection actions are audited.

Task Endpoints

File: src/LearningBank.Api/Endpoints/TaskEndpoints.cs

  • GET /children/{childId}/tasks
  • POST /tasks
  • PUT /tasks/{taskId}
  • POST /tasks/{taskId}/complete
  • GET /children/{childId}/tasks/completions/pending
  • POST /tasks/completions/{completionId}/review

Behavior notes:

  • Parent can create and review tasks for linked children.
  • Child can complete only own tasks.
  • Approved task completion posts a reward transaction.

DTOs and Validation

DTOs live under src/LearningBank.Api/Dtos:

  • UserDtos.cs
  • CategoryDtos.cs
  • TransactionDtos.cs
  • TransferDtos.cs
  • TaskDtos.cs

Validators live in src/LearningBank.Api/Validators/RequestValidators.cs and are registered at startup.

Error Handling

  • Non-development environment uses exception handler returning RFC 7807 style payload with status 500.
  • Domain failures such as insufficient funds are mapped to 422 responses.
  • Rate limit rejections return 429.

Health and Observability

  • Health endpoint: GET /health
  • Request logging: app.UseSerilogRequestLogging
  • Minimum logging levels are configured in appsettings files.

Data Flow Summary

  1. Request enters API endpoint.
  2. Claims are transformed and role is resolved.
  3. Endpoint authorizes actor and validates input.
  4. Domain entities/services enforce financial invariants.
  5. Repository operations execute in infrastructure context.
  6. Unit of work commits transaction.
  7. Response DTO is returned.

Testing Status

  • API tests currently cover claims transformation and transaction visibility/repository behavior.
  • Integration tests through Microsoft.AspNetCore.Mvc.Testing are not yet implemented.

Recommended Next Improvements

  • Add integration tests using Microsoft.AspNetCore.Mvc.Testing.
  • Add explicit problem details payload model for all non-success responses.
  • Add OpenAPI generation for endpoint discoverability.