Lyo.Api.Models 1.0.1

Lyo.Api.Models

Shared HTTP contract models for Lyo minimal APIs and their clients—distinct from Lyo.Query.Models (filter trees + projection DTOs).

Request envelopes

Builders follow method-chaining ergonomics so gateways/tests avoid object initializer noise.

Response envelopes

Concrete result records emitted by Lyo.Api endpoints (see Common/Response/Result.cs and Common/Response/ResultFactory.cs). There is no generic ApiResponse<T> / BulkApiResponse<T> — each operation has its own typed envelope:

Use ResultFactory.QuerySuccess / ProjectedQuerySuccess / CreateBulk / UpdateBulk / …` to build envelopes from CRUD service code — they pre-compute counts, query scores, and split success vs failure paths.

Other models & metadata

• CrudMetadata — standardized success payload fragments (timestamps, concurrency tokens if host sets them).
• FileUpload / FileUploadRes — bridge file pipeline results.
• CacheItem (record + CacheItemTypeEnum Key / Tag) — describes server cache entries surfaced by introspection endpoints; helpers CacheItem.Key(name) / CacheItem.Tag(name) build instances and the record’s GetHashCode / ToString are stable for set membership.
• Constants.ApiErrorCodes — single source of truth for stable errors[].code strings on problem responses (Unknown, InvalidQuery, InvalidField, InvalidPaging, NotFound, Forbidden, Cancelled, SqlException, MessageQueueConnectionIssue, Conflict, ExceedMaxBulkSize, etc.). Check before duplicating literals in clients.

Errors & Problem Details

• LyoProblemDetails (record) / ILyoProblemDetails — RFC 9457 problem details serialized with the default JSON contract; carries Detail, Status, Timestamp, Errors (array of ApiError), Title, Type, Instance, TraceId, SpanId, optional Stacktrace, and bag-of-extensions. Helpers: MapErrorCodeToHttpStatus(code) ( uses Constants.ApiErrorCodes), FromCode(errorCode, detail, …), and HttpStatusTitle(statusCode) (used by export wrapping).
• ApiError (record) — single entry in errors[]: Code, Description, optional Stacktrace.
• ApiErrorException — sealed Exception carrying a LyoProblemDetails; thrown when an operation fails with a structured problem (e.g. export over a failed projected query).
• InvalidPropertyNameException — thrown when patch keys do not exist on the target type (surfaced as InvalidPatchRequest).
• LFException (Error/LFException.cs) — domain-level Lyo exception carrying a stable ErrorCode; hosts (e.g. Lyo.Api's LoggingMiddleware) translate it into warning-level LyoProblemDetails.
• LyoProblemDetailsBuilder — fluent builder for trace/span/route fields, message and error-code overrides, and AddApiError / FromException shortcuts.

Caching & diagnostics

CacheItem + CacheItemTypeEnum describe server cache introspection endpoints (used by internal tools & load tests). QueryRequestScorer, QueryRequestScoreBreakdown support explainability endpoints around query planning (pair with scoring fields on ResultFactory outputs + server logs).

Relationship to Lyo.Result

Some server modules choose Lyo.Result internally; ProblemDetails remain the wire representation while Lyo.Result informs * domain* logic in process boundaries.

Versioning guidance

• Add [JsonPropertyName] compatibility shims during transition windows.
• Document dual-read servers before removing legacy names.
• Prefer additive optional properties over reinterpretation of existing ones.

Consumers

• Minimal API hosts (Lyo.Api) reference these types directly in endpoint signatures.
• Remote workers use the same models with Lyo.Api.Client to eliminate translation layers.

Dependencies

Generated from ProjectReference / PackageReference (same model as docs/Lyo.ProjectGraph.html).

• Lyo.Common — (direct, lyo)
• Lyo.DateAndTime — (direct, lyo)
• Lyo.Exceptions — (direct, lyo)
• Lyo.Query.Models — (direct, lyo)
• Microsoft.Extensions.Logging.Abstractions 10.0.5 — (transitive, microsoft)
• System.Memory 4.6.3 — (transitive, microsoft, netstandard2.0)
• System.Text.Json 10.0.5 — (transitive, microsoft, netstandard2.0)