Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Stabilize v1 API contracts with response envelopes

Yuechen Li9fcb245e1015
diff --git a/Aetheris.Server.Tests/KernelApiIntegrationTests.cs b/Aetheris.Server.Tests/KernelApiIntegrationTests.cs
index 75ebb044..5b1b157d 100644
--- a/Aetheris.Server.Tests/KernelApiIntegrationTests.cs
+++ b/Aetheris.Server.Tests/KernelApiIntegrationTests.cs
@@ -15,29 +15,35 @@ public sealed class KernelApiIntegrationTests : IClassFixture<WebApplicationFact
}
[Fact]
- public async Task CreateDocument_CreateBox_TessellateAndPick_Succeeds()
+ public async Task V1_CreateDocument_CreateBox_TessellateAndPick_ReturnsExpectedEnvelope()
{
- var document = await CreateDocumentAsync();
+ var document = await CreateDocumentAsync("/api/v1/documents");
var boxResponse = await _client.PostAsJsonAsync(
- $"/api/documents/{document.DocumentId}/bodies/primitives/box",
+ $"/api/v1/documents/{document.Data!.DocumentId}/bodies/primitives/box",
new BoxCreateRequestDto(2, 2, 2));
boxResponse.EnsureSuccessStatusCode();
- var boxBody = await boxResponse.Content.ReadFromJsonAsync<BodyCreatedResponseDto>();
+ var boxBody = await boxResponse.Content.ReadFromJsonAsync<ApiResponseDto<BodyCreatedResponseDto>>();
Assert.NotNull(boxBody);
+ Assert.True(boxBody!.Success);
+ Assert.NotNull(boxBody.Data);
+ Assert.Empty(boxBody.Diagnostics);
var tessellationResponse = await _client.PostAsJsonAsync(
- $"/api/documents/{document.DocumentId}/bodies/{boxBody!.BodyId}/tessellate",
+ $"/api/v1/documents/{document.Data.DocumentId}/bodies/{boxBody.Data!.BodyId}/tessellate",
new TessellateRequestDto(null));
tessellationResponse.EnsureSuccessStatusCode();
- var tessellation = await tessellationResponse.Content.ReadFromJsonAsync<TessellationResponseDto>();
+ var tessellation = await tessellationResponse.Content.ReadFromJsonAsync<ApiResponseDto<TessellationResponseDto>>();
Assert.NotNull(tessellation);
- Assert.NotEmpty(tessellation!.FacePatches);
+ Assert.True(tessellation!.Success);
+ Assert.NotNull(tessellation.Data);
+ Assert.NotEmpty(tessellation.Data!.FacePatches);
+ Assert.Empty(tessellation.Diagnostics);
var pickResponse = await _client.PostAsJsonAsync(
- $"/api/documents/{document.DocumentId}/bodies/{boxBody.BodyId}/pick",
+ $"/api/v1/documents/{document.Data.DocumentId}/bodies/{boxBody.Data.BodyId}/pick",
new PickRequestDto(
new Point3Dto(0, 0, 5),
new Vector3Dto(0, 0, -1),
@@ -45,20 +51,22 @@ public sealed class KernelApiIntegrationTests : IClassFixture<WebApplicationFact
PickOptions: new PickOptionsDto(NearestOnly: true, IncludeBackfaces: null, EdgeTolerance: null, SortTieTolerance: null, MaxDistance: null)));
pickResponse.EnsureSuccessStatusCode();
- var pick = await pickResponse.Content.ReadFromJsonAsync<PickResponseDto>();
+ var pick = await pickResponse.Content.ReadFromJsonAsync<ApiResponseDto<PickResponseDto>>();
Assert.NotNull(pick);
- Assert.Single(pick!.Hits);
+ Assert.True(pick!.Success);
+ Assert.NotNull(pick.Data);
+ Assert.Single(pick.Data!.Hits);
+ Assert.NotNull(pick.Data.Hits[0].Point);
}
[Fact]
- public async Task UnsupportedBoolean_ReturnsStructuredError()
+ public async Task UnsupportedBoolean_OnV1_ReturnsUnprocessableEntityWithDiagnosticEnvelope()
{
- var document = await CreateDocumentAsync();
- var left = await CreateBoxAsync(document.DocumentId, 1, 1, 1);
- var right = await CreateBoxAsync(document.DocumentId, 1, 1, 1);
+ var document = await CreateDocumentAsync("/api/v1/documents");
+ var left = await CreateBoxAsync("/api/v1/documents", document.Data!.DocumentId, 1, 1, 1);
var extrudeResponse = await _client.PostAsJsonAsync(
- $"/api/documents/{document.DocumentId}/operations/extrude",
+ $"/api/v1/documents/{document.Data.DocumentId}/operations/extrude",
new ExtrudeRequestDto(
[new ProfilePoint2Dto(-0.5, -0.5), new ProfilePoint2Dto(0.5, -0.5), new ProfilePoint2Dto(0.5, 0.5), new ProfilePoint2Dto(-0.5, 0.5)],
new Point3Dto(4, 0, 0),
@@ -67,48 +75,79 @@ public sealed class KernelApiIntegrationTests : IClassFixture<WebApplicationFact
1));
extrudeResponse.EnsureSuccessStatusCode();
- var moved = await extrudeResponse.Content.ReadFromJsonAsync<BodyCreatedResponseDto>();
+ var moved = await extrudeResponse.Content.ReadFromJsonAsync<ApiResponseDto<BodyCreatedResponseDto>>();
Assert.NotNull(moved);
+ Assert.NotNull(moved!.Data);
var booleanResponse = await _client.PostAsJsonAsync(
- $"/api/documents/{document.DocumentId}/operations/boolean",
- new BooleanRequestDto(left.BodyId, moved!.BodyId, "union"));
+ $"/api/v1/documents/{document.Data.DocumentId}/operations/boolean",
+ new BooleanRequestDto(left.Data!.BodyId, moved.Data!.BodyId, "union"));
Assert.Equal(HttpStatusCode.UnprocessableEntity, booleanResponse.StatusCode);
- var error = await booleanResponse.Content.ReadFromJsonAsync<ErrorResponseDto>();
- Assert.NotNull(error);
- Assert.Contains(error!.Diagnostics, d => d.Code == "NotImplemented");
+ var envelope = await booleanResponse.Content.ReadFromJsonAsync<ApiResponseDto<object>>();
+ Assert.NotNull(envelope);
+ Assert.False(envelope!.Success);
+ Assert.Null(envelope.Data);
+ Assert.Contains(envelope.Diagnostics, d => d.Code == "NotImplemented");
+ Assert.All(envelope.Diagnostics, d =>
+ {
+ Assert.False(string.IsNullOrWhiteSpace(d.Code));
+ Assert.False(string.IsNullOrWhiteSpace(d.Severity));
+ Assert.False(string.IsNullOrWhiteSpace(d.Message));
+ });
}
[Fact]
- public async Task MissingDocumentAndBody_ReturnNotFound()
+ public async Task MissingDocumentAndBody_OnV1_ReturnNotFoundWithDiagnosticEnvelope()
{
var missingDocId = Guid.NewGuid();
var missingBodyId = Guid.NewGuid();
- var docResponse = await _client.GetAsync($"/api/documents/{missingDocId}");
+ var docResponse = await _client.GetAsync($"/api/v1/documents/{missingDocId}");
Assert.Equal(HttpStatusCode.NotFound, docResponse.StatusCode);
+ var missingDoc = await docResponse.Content.ReadFromJsonAsync<ApiResponseDto<object>>();
+ Assert.NotNull(missingDoc);
+ Assert.False(missingDoc!.Success);
+ Assert.NotEmpty(missingDoc.Diagnostics);
- var created = await CreateDocumentAsync();
+ var created = await CreateDocumentAsync("/api/v1/documents");
var bodyResponse = await _client.PostAsJsonAsync(
- $"/api/documents/{created.DocumentId}/bodies/{missingBodyId}/tessellate",
+ $"/api/v1/documents/{created.Data!.DocumentId}/bodies/{missingBodyId}/tessellate",
new TessellateRequestDto(null));
Assert.Equal(HttpStatusCode.NotFound, bodyResponse.StatusCode);
+
+ var missingBody = await bodyResponse.Content.ReadFromJsonAsync<ApiResponseDto<object>>();
+ Assert.NotNull(missingBody);
+ Assert.False(missingBody!.Success);
+ Assert.NotEmpty(missingBody.Diagnostics);
+ }
+
+ [Fact]
+ public async Task UnversionedRoute_CompatibilityAlias_StillWorks()
+ {
+ var response = await _client.PostAsJsonAsync("/api/documents", new DocumentCreateRequestDto("compat"));
+ response.EnsureSuccessStatusCode();
+
+ var envelope = await response.Content.ReadFromJsonAsync<ApiResponseDto<DocumentCreateResponseDto>>();
+ Assert.NotNull(envelope);
+ Assert.True(envelope!.Success);
+ Assert.NotNull(envelope.Data);
+ Assert.Equal("compat", envelope.Data!.Name);
}
- private async Task<DocumentCreateResponseDto> CreateDocumentAsync()
+ private async Task<ApiResponseDto<DocumentCreateResponseDto>> CreateDocumentAsync(string routePrefix)
{
- var response = await _client.PostAsJsonAsync("/api/documents", new DocumentCreateRequestDto("test"));
+ var response = await _client.PostAsJsonAsync(routePrefix, new DocumentCreateRequestDto("test"));
response.EnsureSuccessStatusCode();
- var payload = await response.Content.ReadFromJsonAsync<DocumentCreateResponseDto>();
+ var payload = await response.Content.ReadFromJsonAsync<ApiResponseDto<DocumentCreateResponseDto>>();
return payload!;
}
- private async Task<BodyCreatedResponseDto> CreateBoxAsync(Guid documentId, double w, double h, double d)
+ private async Task<ApiResponseDto<BodyCreatedResponseDto>> CreateBoxAsync(string routePrefix, Guid documentId, double w, double h, double d)
{
- var response = await _client.PostAsJsonAsync($"/api/documents/{documentId}/bodies/primitives/box", new BoxCreateRequestDto(w, h, d));
+ var response = await _client.PostAsJsonAsync($"{routePrefix}/{documentId}/bodies/primitives/box", new BoxCreateRequestDto(w, h, d));
response.EnsureSuccessStatusCode();
- var body = await response.Content.ReadFromJsonAsync<BodyCreatedResponseDto>();
+ var body = await response.Content.ReadFromJsonAsync<ApiResponseDto<BodyCreatedResponseDto>>();
return body!;
}
}
diff --git a/Aetheris.Server/Api/ApiMappings.cs b/Aetheris.Server/Api/ApiMappings.cs
index 924befdb..b5194803 100644
--- a/Aetheris.Server/Api/ApiMappings.cs
+++ b/Aetheris.Server/Api/ApiMappings.cs
@@ -10,11 +10,14 @@ namespace Aetheris.Server.Api;
public static class ApiMappings
{
+ public static IResult Ok<T>(T data)
+ => Results.Ok(new ApiResponseDto<T>(true, data, []));
+
public static IResult KernelFailure(IReadOnlyList<KernelDiagnostic> diagnostics)
{
var mapped = diagnostics.Select(ToDiagnostic).ToArray();
var statusCode = ResolveStatusCode(diagnostics);
- return Results.Json(new ErrorResponseDto(mapped), statusCode: statusCode);
+ return Results.Json(new ApiResponseDto<object>(false, null, mapped), statusCode: statusCode);
}
public static DiagnosticDto ToDiagnostic(KernelDiagnostic diagnostic)
@@ -41,7 +44,7 @@ public static class ApiMappings
public static IResult NotFound(string message, string source)
{
var diagnostic = new KernelDiagnostic(KernelDiagnosticCode.InvalidArgument, KernelDiagnosticSeverity.Error, message, source);
- return Results.NotFound(new ErrorResponseDto([ToDiagnostic(diagnostic)]));
+ return Results.NotFound(new ApiResponseDto<object>(false, null, [ToDiagnostic(diagnostic)]));
}
public static Point3Dto ToPointDto(Point3D point) => new(point.X, point.Y, point.Z);
@@ -72,8 +75,8 @@ public static class ApiMappings
h.SourcePatchIndex,
h.SourcePrimitiveIndex)).ToArray());
- public static BadRequest<ErrorResponseDto> BadRequestFromMessage(string message, string source)
- => TypedResults.BadRequest(new ErrorResponseDto([new DiagnosticDto(
+ public static BadRequest<ApiResponseDto<object>> BadRequestFromMessage(string message, string source)
+ => TypedResults.BadRequest(new ApiResponseDto<object>(false, null, [new DiagnosticDto(
KernelDiagnosticCode.InvalidArgument.ToString(),
KernelDiagnosticSeverity.Error.ToString(),
message,
diff --git a/Aetheris.Server/Api/KernelEndpoints.cs b/Aetheris.Server/Api/KernelEndpoints.cs
index d1f7cf14..a6c7d645 100644
--- a/Aetheris.Server/Api/KernelEndpoints.cs
+++ b/Aetheris.Server/Api/KernelEndpoints.cs
@@ -13,12 +13,16 @@ public static class KernelEndpoints
{
public static void MapKernelApi(this WebApplication app)
{
- var documents = app.MapGroup("/api/documents");
+ MapDocumentRoutes(app.MapGroup("/api/v1/documents"));
+ MapDocumentRoutes(app.MapGroup("/api/documents"));
+ }
+ private static void MapDocumentRoutes(RouteGroupBuilder documents)
+ {
documents.MapPost("", (DocumentCreateRequestDto? request, KernelDocumentStore store) =>
{
var created = store.Create(request?.Name);
- return Results.Ok(new DocumentCreateResponseDto(created.Id, created.Name, Volatile: true));
+ return ApiMappings.Ok(new DocumentCreateResponseDto(created.Id, created.Name, Volatile: true));
});
documents.MapGet("/{documentId:guid}", (Guid documentId, KernelDocumentStore store) =>
@@ -29,7 +33,7 @@ public static class KernelEndpoints
}
var bodyIds = document.SnapshotBodies().Keys.OrderBy(id => id).ToArray();
- return Results.Ok(new DocumentSummaryResponseDto(document.Id, document.Name, bodyIds.Length, bodyIds));
+ return ApiMappings.Ok(new DocumentSummaryResponseDto(document.Id, document.Name, bodyIds.Length, bodyIds));
});
documents.MapPost("/{documentId:guid}/bodies/primitives/box", (Guid documentId, BoxCreateRequestDto request, KernelDocumentStore store) =>
@@ -41,7 +45,7 @@ public static class KernelEndpoints
return ApiMappings.KernelFailure(kernel.Diagnostics);
}
- return Results.Ok(CreateBodyResponse(document, kernel.Value));
+ return ApiMappings.Ok(CreateBodyResponse(document, kernel.Value));
}));
documents.MapPost("/{documentId:guid}/bodies/primitives/cylinder", (Guid documentId, CylinderCreateRequestDto request, KernelDocumentStore store) =>
@@ -53,7 +57,7 @@ public static class KernelEndpoints
return ApiMappings.KernelFailure(kernel.Diagnostics);
}
- return Results.Ok(CreateBodyResponse(document, kernel.Value));
+ return ApiMappings.Ok(CreateBodyResponse(document, kernel.Value));
}));
documents.MapPost("/{documentId:guid}/bodies/primitives/sphere", (Guid documentId, SphereCreateRequestDto request, KernelDocumentStore store) =>
@@ -65,7 +69,7 @@ public static class KernelEndpoints
return ApiMappings.KernelFailure(kernel.Diagnostics);
}
- return Results.Ok(CreateBodyResponse(document, kernel.Value));
+ return ApiMappings.Ok(CreateBodyResponse(document, kernel.Value));
}));
documents.MapPost("/{documentId:guid}/operations/extrude", (Guid documentId, ExtrudeRequestDto request, KernelDocumentStore store) =>
@@ -88,7 +92,7 @@ public static class KernelEndpoints
return ApiMappings.KernelFailure(kernel.Diagnostics);
}
- return Results.Ok(CreateBodyResponse(document, kernel.Value));
+ return ApiMappings.Ok(CreateBodyResponse(document, kernel.Value));
}));
documents.MapPost("/{documentId:guid}/operations/revolve", (Guid documentId, RevolveRequestDto request, KernelDocumentStore store) =>
@@ -129,7 +133,7 @@ public static class KernelEndpoints
return ApiMappings.KernelFailure(kernel.Diagnostics);
}
- return Results.Ok(CreateBodyResponse(document, kernel.Value));
+ return ApiMappings.Ok(CreateBodyResponse(document, kernel.Value));
}));
documents.MapPost("/{documentId:guid}/operations/boolean", (Guid documentId, BooleanRequestDto request, KernelDocumentStore store) =>
@@ -163,7 +167,7 @@ public static class KernelEndpoints
return ApiMappings.KernelFailure(kernel.Diagnostics);
}
- return Results.Ok(CreateBodyResponse(document, kernel.Value));
+ return ApiMappings.Ok(CreateBodyResponse(document, kernel.Value));
}));
documents.MapPost("/{documentId:guid}/bodies/{bodyId:guid}/tessellate", (Guid documentId, Guid bodyId, TessellateRequestDto? request, KernelDocumentStore store) =>
@@ -176,7 +180,7 @@ public static class KernelEndpoints
return ApiMappings.KernelFailure(kernel.Diagnostics);
}
- return Results.Ok(ApiMappings.ToTessellationResponse(kernel.Value));
+ return ApiMappings.Ok(ApiMappings.ToTessellationResponse(kernel.Value));
}));
documents.MapPost("/{documentId:guid}/bodies/{bodyId:guid}/pick", (Guid documentId, Guid bodyId, PickRequestDto request, KernelDocumentStore store) =>
@@ -199,7 +203,7 @@ public static class KernelEndpoints
return ApiMappings.KernelFailure(kernel.Diagnostics);
}
- return Results.Ok(ApiMappings.ToPickResponse(kernel.Value));
+ return ApiMappings.Ok(ApiMappings.ToPickResponse(kernel.Value));
}));
}
diff --git a/Aetheris.Server/Contracts/ApiContracts.cs b/Aetheris.Server/Contracts/ApiContracts.cs
index 28804d55..7539bed6 100644
--- a/Aetheris.Server/Contracts/ApiContracts.cs
+++ b/Aetheris.Server/Contracts/ApiContracts.cs
@@ -2,7 +2,7 @@ namespace Aetheris.Server.Contracts;
public sealed record DiagnosticDto(string Code, string Severity, string Message, string? Source);
-public sealed record ErrorResponseDto(IReadOnlyList<DiagnosticDto> Diagnostics);
+public sealed record ApiResponseDto<T>(bool Success, T? Data, IReadOnlyList<DiagnosticDto> Diagnostics);
public sealed record DocumentCreateRequestDto(string? Name);
diff --git a/docs/milestones.md b/docs/milestones.md
index 6db14bc2..f9a118ed 100644
--- a/docs/milestones.md
+++ b/docs/milestones.md
@@ -144,3 +144,13 @@
- [x] Add deterministic kernel diagnostic-to-HTTP mapping with structured error payloads for invalid, unsupported, validation, and missing-resource paths.
- [x] Add focused integration tests for core happy paths and deterministic error behavior.
- [x] Defer frontend integration details and API versioning to M17+.
+
+## M17 — Web Protocol Stabilization + Versioned Contracts v1
+
+- [x] Stabilize the canonical backend API surface under `/api/v1/documents/...` for frontend integration.
+- [x] Adopt a consistent HTTP response envelope for all routes: `success`, `data`, `diagnostics`.
+- [x] Normalize diagnostics payload shape (`code`, `severity`, `message`, `source`) for all errors, including not-found responses.
+- [x] Preserve M16 capability coverage (document summary/create, primitives, extrude/revolve/boolean, tessellate, pick) while standardizing protocol shape only.
+- [x] Keep temporary unversioned compatibility aliases under `/api/documents/...` during migration; v1 routes are canonical.
+- [x] Add integration tests that lock versioned route behavior, envelope shape, diagnostics determinism, and compatibility alias behavior.
+- [x] M18 frontend integration targets stable v1 contracts and envelope semantics.