APIs¶

Target Architecture — Final-State Design

The 10 endpoints below are the planned public REST surface of the ConnectSoft.Factory.Templates.* services. Routes follow the Naming Conventions (plural, hyphenated collections; verb sub-paths for non-CRUD actions). All requests carry tenant context and emit canonical event envelope events.

The platform exposes a small, deliberate public API: register and discover templates and libraries, execute and validate templates, and evaluate compatibility. Everything else (versioning internals, dependency scans, publishing mechanics, upgrade advice) is internal gRPC or event-driven, consumed within the platform or by trusted factory platforms.

API surfaces¶

Surface	Audience	Transport	Examples
Public REST	Agent Mesh, Factory Studio, Marketplace, authorized partners	HTTPS/JSON	The 10 endpoints below
Internal gRPC	Other `ConnectSoft.Factory.Templates.*` services	gRPC (mTLS)	Version promotion, dependency scan, matrix compute
Event-driven	All factory platforms	Azure Service Bus	Commands (`VerbNoun`) and events (`NounVerbPastTense`) — see Events

Authorization¶

Authentication — OAuth2 / OIDC bearer tokens issued by the factory authorization server (generated from ConnectSoft.AuthorizationServerTemplate), validated with ConnectSoft.Extensions.Http.OAuth2 and WebSecurity.
Tenant scope — every request resolves a tenantId (token claim or header) via ConnectSoft.Extensions.Saas.AspNetCore; the catalog is tenant-isolated.
Scopes / roles — templates.read, templates.write, templates.execute, templates.publish, libraries.read, libraries.write, libraries.publish. Agents act under delegated scopes tied to their task- id; publishing scopes may require governance approval.
Idempotency — mutating endpoints accept an Idempotency-Key header; the platform deduplicates and the Scaffold Engine enforces idempotent execution.

Versioning¶

The API is versioned by URL prefix (/v1) with additive evolution. Breaking changes introduce /v2. Resource bodies tolerate unknown fields (forward compatible). Template and library content versioning (semantic versions) is independent of API versioning.

Public endpoints¶

1. Register a template¶

POST /v1/templates

{
  "name": "ConnectSoft.Template.Microservice",
  "title": "Microservice",
  "category": "service",
  "owner": "platform-team",
  "tags": ["clean-architecture", "dotnet10", "service"]
}

Response 201 Created:

{
  "templateId": "tmpl-7c1a9f",
  "name": "ConnectSoft.Template.Microservice",
  "category": "service",
  "status": "Active",
  "createdAt": "2026-06-11T09:00:00Z"
}

Emits TemplateRegistered.

2. Get a template¶

GET /v1/templates/{templateId}

Response 200 OK:

{
  "templateId": "tmpl-7c1a9f",
  "name": "ConnectSoft.Template.Microservice",
  "category": "service",
  "status": "Active",
  "versions": [
    { "templateVersionId": "tver-3201", "semanticVersion": "3.2.0", "status": "Published", "targetFramework": "net10.0" },
    { "templateVersionId": "tver-3100", "semanticVersion": "3.1.0", "status": "Deprecated", "targetFramework": "net10.0" }
  ]
}

3. Create a template version¶

POST /v1/templates/{templateId}/versions

{
  "semanticVersion": "3.2.0",
  "sourceRef": "git:templates/microservice@a1b2c3d",
  "engineKind": "DotnetNewTemplatePack",
  "targetFramework": "net10.0",
  "parameterSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": ["serviceName", "namespaceRoot"],
    "properties": {
      "serviceName": { "type": "string" },
      "namespaceRoot": { "type": "string" },
      "persistence": { "enum": ["NHibernate", "EntityFramework", "Dapper", "PostgreSQL", "MongoDb"] },
      "messaging": { "enum": ["MassTransit", "NServiceBus"] },
      "includeAuthorization": { "type": "boolean", "default": false }
    }
  },
  "changelog": "Add metered billing parameter; bump base libraries."
}

Response 201 Created:

{
  "templateVersionId": "tver-3201",
  "semanticVersion": "3.2.0",
  "status": "Draft"
}

Emits TemplateVersionCreated (and TemplateParameterSchemaDefined).

4. Execute a template¶

POST /v1/templates/{templateId}/execute

{
  "templateVersionId": "tver-3201",
  "parameters": {
    "serviceName": "Reservations",
    "namespaceRoot": "Contoso.Booking",
    "persistence": "PostgreSQL",
    "messaging": "MassTransit",
    "includeAuthorization": true
  },
  "libraries": [
    { "packageName": "ConnectSoft.Extensions.PersistenceModel.PostgreSQL", "version": "4.1.0" },
    { "packageName": "ConnectSoft.Extensions.MessagingModel.MassTransit", "version": "5.0.0" }
  ],
  "target": { "repository": "git:contoso/booking-reservations", "branch": "main" },
  "correlation": { "agentTaskId": "task-4d21" }
}

Response 202 Accepted:

{
  "executionId": "exec-9a2b",
  "status": "Requested",
  "scaffoldOutputId": null
}

On completion emits ScaffoldGenerated then TemplateExecuted. Poll GET /v1/templates/{templateId}/executions/{executionId} or subscribe to events for the resulting scaffoldOutputId.

5. Validate a template¶

POST /v1/templates/{templateId}/validate

{
  "templateVersionId": "tver-3201",
  "checks": ["StructuralLint", "ParameterSchema", "SampleGeneration"]
}

Response 200 OK:

{
  "validationResultId": "tval-55ce",
  "templateVersionId": "tver-3201",
  "outcome": "Passed",
  "findings": []
}

Emits TemplateValidated.

6. Evaluate template compatibility¶

POST /v1/templates/{templateId}/compatibility/evaluate

{
  "templateVersionId": "tver-3201",
  "runtime": "net10.0",
  "libraries": [
    { "packageName": "ConnectSoft.Extensions.PersistenceModel.PostgreSQL", "version": "4.1.0" },
    { "packageName": "ConnectSoft.Extensions.MessagingModel.MassTransit", "version": "5.0.0" }
  ]
}

Response 200 OK:

{
  "matrixId": "cmtx-7f10",
  "compatible": true,
  "violations": []
}

A failure returns compatible: false with violations listing each broken TemplateCompatibilityRule. Emits CompatibilityEvaluated.

7. Register a library¶

POST /v1/libraries

{
  "packageName": "ConnectSoft.Extensions.PersistenceModel.PostgreSQL",
  "area": "persistence",
  "owner": "platform-team",
  "capabilities": [
    { "name": "RelationalPersistence", "contract": "IRepository" },
    { "name": "PostgreSqlProvider", "contract": "IDbProvider" }
  ],
  "tags": ["persistence", "postgresql", "nhibernate"]
}

Response 201 Created:

{ "libraryId": "lib-22a0", "packageName": "ConnectSoft.Extensions.PersistenceModel.PostgreSQL", "status": "Active" }

Emits LibraryRegistered.

8. Get a library¶

GET /v1/libraries/{libraryId}

{
  "libraryId": "lib-22a0",
  "packageName": "ConnectSoft.Extensions.PersistenceModel.PostgreSQL",
  "area": "persistence",
  "capabilities": [ { "name": "RelationalPersistence", "contract": "IRepository" } ],
  "versions": [ { "libraryVersionId": "lver-410", "semanticVersion": "4.1.0", "targetFramework": "net10.0", "status": "Published" } ]
}

9. Search libraries¶

POST /v1/libraries/search

{
  "capability": "MeteredBilling",
  "area": "saas",
  "targetFramework": "net10.0",
  "includeApiClients": false
}

Response 200 OK:

{
  "results": [
    { "libraryId": "lib-77f3", "packageName": "ConnectSoft.Extensions.Saas.Metering", "matchedCapability": "MeteredBilling", "latestVersion": "2.3.0" }
  ]
}

Capability-based search is the primary discovery path for agents; ApiClientCatalogService results are included when includeApiClients is true.

10. Evaluate library compatibility¶

POST /v1/libraries/compatibility/evaluate

{
  "runtime": "net10.0",
  "libraries": [
    { "packageName": "ConnectSoft.Extensions.Saas.AspNetCore", "version": "2.3.0" },
    { "packageName": "ConnectSoft.Extensions.MessagingModel.MassTransit", "version": "5.0.0" },
    { "packageName": "ConnectSoft.Extensions.MessagingModel.NServiceBus", "version": "6.0.0" }
  ]
}

Response 200 OK:

{
  "matrixId": "cmtx-8a31",
  "compatible": false,
  "violations": [
    {
      "rule": "LibraryConflictsWith",
      "detail": "MessagingModel.MassTransit conflicts with MessagingModel.NServiceBus in the same composition",
      "suggestedResolution": "Remove one messaging stack"
    }
  ]
}

Emits CompatibilityEvaluated; the advisor populates suggestedResolution.

Endpoint summary¶

#	Method & path	Service	Emits
1	`POST /v1/templates`	TemplateRegistryService	`TemplateRegistered`
2	`GET /v1/templates/{templateId}`	TemplateRegistryService	—
3	`POST /v1/templates/{templateId}/versions`	TemplateVersionService	`TemplateVersionCreated`
4	`POST /v1/templates/{templateId}/execute`	ScaffoldEngineService	`ScaffoldGenerated`, `TemplateExecuted`
5	`POST /v1/templates/{templateId}/validate`	TemplateValidationService	`TemplateValidated`
6	`POST /v1/templates/{templateId}/compatibility/evaluate`	TemplateCompatibilityService	`CompatibilityEvaluated`
7	`POST /v1/libraries`	LibraryRegistryService	`LibraryRegistered`
8	`GET /v1/libraries/{libraryId}`	LibraryRegistryService	—
9	`POST /v1/libraries/search`	LibraryRegistryService / ApiClientCatalogService	—
10	`POST /v1/libraries/compatibility/evaluate`	CompatibilityMatrixService	`CompatibilityEvaluated`

APIs¶

API surfaces¶

Authorization¶

Versioning¶

Public endpoints¶

1. Register a template¶

2. Get a template¶

3. Create a template version¶

4. Execute a template¶

5. Validate a template¶

6. Evaluate template compatibility¶

7. Register a library¶

8. Get a library¶

9. Search libraries¶

10. Evaluate library compatibility¶

Endpoint summary¶

Related¶