EAC.Infrastructure.Api.JsonApi 0.1.0-rc.4

EAC.Infrastructure.Api.JsonApi

Desde 2026-10-09, Native AOT queda fuera del alcance por decisión del usuario. No se declara compatibilidad ni se exige su gate. Las referencias históricas no constituyen soporte vigente; build y tests ordinarios siguen siendo obligatorios.

Desarrollo desde el workspace

El incremento fuente agrega JsonApiRequestReader, JsonApiRequestDocument<T>, JsonApiResourceInput<T>, JsonApiResults.Error y JsonApiPaginationMetadata para compartir la frontera JSON:API entre endpoints. La lectura usa metadata source-generated y los errores conservan correlación. Los contratos de negocio y converters del servicio permanecen en su propietario. Estas APIs se consumen por ProjectReference; este incremento no está publicado.

El incremento fuente también incorpora JsonApiLinks para enlaces opcionales en documentos, recursos y relaciones, además de metadata JSON explícita en recursos y relaciones. JsonApiLinks.FromPagination reutiliza la paginación existente y serializa prev conforme a JSON:API. Consulte la guía de hipermedia.

El proyecto referencia el código fuente de eac-foundation y eac-infrastructure-api-http, situados como repositorios hermanos. La solución incluye esas dependencias para compilarlas con la misma configuración. Antes de ejecutar scripts/ci.sh, deben estar presentes los tres repositorios; no se utiliza el paquete publicado como alternativa local.

Repositorio propietario del NuGet EAC.Infrastructure.Api.JsonApi.

Estado actual: trece reglas trazadas en el código fuente, configuración nativa validada y smoke Native AOT; versión 0.1.0-rc.3 publicada. Las adiciones fuente indicadas arriba todavía no están publicadas.

La validación común de entrada se conecta con una asignación: options.ValidateRequest = JsonApiRequestValidation.ValidateAsync. El adaptador valida Content-Type sin negociar Accept y reutiliza errores negociados con estado 415; no duplica el pipeline del host.

Los contratos declarativos de Contracts incorporan atributos para recursos, requests, campos y relaciones. Un generador consumidor puede implementar IJsonApiResourceDescriptor con tipos y definiciones explícitas; el runtime no descubre atributos por reflexión. Es una ampliación aditiva no publicada, consumida por ProjectReference. Consulte la guía declarativa.

JsonApiNegotiatedResults compone recursos, páginas y errores con el adaptador neutral EAC.Infrastructure.Api.Http: el cliente elige JSON simple o JSON:API. Ambos repositorios se consumen por ProjectReference durante desarrollo. El servicio aporta DTOs, mappers explícitos y enlaces de negocio; no repite envelopes, negociación ni mapeo protocolar de errores.

La composición de cada API puede registrar una vez descriptores inmutables JsonApiResultResourceDescriptor y JsonApiResultPageDescriptor. Cada descriptor conserva mapper, enlaces, incluidos y JsonTypeInfo generado. El handler recibe IJsonApiResultRegistry por DI y escribe el recurso o página con su Result, contexto y tipo de respuesta. No hay descubrimiento de DTOs, serialización por reflexión ni localizador de servicios; duplicados o descriptores ausentes devuelven un diagnóstico de los tipos implicados.

• Índice documental
• Guía de consumo y configuración
• JSON:API
• Integración de Validation
• Plan de implementación
• Arquitectura transversal

Uso actual

Instalación:

<PackageReference Include="EAC.Infrastructure.Api.JsonApi" Version="0.1.0-rc.3" />

Registro mínimo, conservando los valores seguros predeterminados:

builder.Services.AddEacJsonApi();

Para enlazar límites operativos desde las fuentes nativas de configuración de .NET, se entrega la configuración del host:

builder.Services.AddEacJsonApi(builder.Configuration);

Configuración completa con sus valores predeterminados:

{
  "Eac": {
    "Api": {
      "JsonApi": {
        "Validation": {
          "MaximumPublishedErrors": 100
        },
        "Query": {
          "DefaultPageSize": 20,
          "MaximumPageSize": 100,
          "MaximumIncludeDepth": 3,
          "MaximumIncludes": 10
        }
      }
    }
  }
}

Equivalencia mediante variables de entorno:

Eac__Api__JsonApi__Validation__MaximumPublishedErrors=100
Eac__Api__JsonApi__Query__DefaultPageSize=20
Eac__Api__JsonApi__Query__MaximumPageSize=100
Eac__Api__JsonApi__Query__MaximumIncludeDepth=3
Eac__Api__JsonApi__Query__MaximumIncludes=10

No existen secretos ni conexiones propiedad de este paquete. Las opciones se validan al inicio; un valor inválido impide arrancar. Los cambios requieren reiniciar el proceso. Una configuración posterior por código tiene precedencia:

builder.Services.Configure<EacJsonApiQueryOptions>(options =>
    options.MaximumPageSize = 50);

Las definiciones de recursos, campos, filtros, sorts, perfiles y extensiones son contratos de código y no se trasladan a appsettings.json.

La negociación recibe los valores HTTP de Content-Type y Accept y devuelve el estado, media type de respuesta y capacidades aplicadas:

var options = new JsonApiNegotiationOptions();
options.Profiles.Add("https://example.com/profiles/compact");

var negotiator = new JsonApiMediaTypeNegotiator(options);
var result = negotiator.Negotiate(
    contentType: null,
    accept: ["application/vnd.api+json;profile=\"https://example.com/profiles/compact\""]);

Los documentos válidos usan tipos distintos, por lo que data y errors no pueden coexistir:

var data = new JsonApiDocument<string> { Data = "value" };
var errors = new JsonApiErrorsDocument<string>(["failure"]);
var metadata = new JsonApiMetaDocument
{
    Meta = new Dictionary<string, object?> { ["count"] = 1 },
};

Los recursos y consultas se construyen mediante contratos explícitos, sin reflexión ni exposición de IQueryable. El endpoint puede recibir IOptions<EacJsonApiQueryOptions> queryOptions desde DI:

var definition = new JsonApiResourceDefinition("orders")
    .AllowField("number")
    .AllowInclude("holder")
    .AllowSort("number")
    .AllowFilter("status", "active", "inactive");

var query = JsonApiQueryParser.Parse(requestQuery, definition, queryOptions.Value);
var resource = new JsonApiResource<object>("orders", "42", new { Number = "A-1" });

Los errores de Validation publican únicamente fuentes declaradas:

var map = new JsonApiValidationMapBuilder<CreateOrderCommand>()
    .Attribute("EffectiveDate", "effectiveDate")
    .Relationship("HolderId", "holder")
    .Build();

var mapping = JsonApiErrorMapper.MapValidation(validationError, map, traceId);