Cohesive Api

Cohesive.Api is a semantic API definition layer. It provides a C# authoring DSL and an immutable API IR that can be projected onto concrete API surfaces such as ASP.NET Minimal APIs, OpenAPI, GraphQL, generated JavaScript and TypeScript clients, and future gRPC bindings.

The purpose is to define the API once as product semantics: operations, routes, request shapes, response variants, parameters, transitions, identity scopes, summaries, tags, and transport metadata. Adapters then bind that definition to the infrastructure that serves, documents, tests, or consumes the API.

• Why It Exists
• API As IR
• ASP.NET Minimal API Binding
• Identity And Scope Policies
• OpenAPI Projection
• GraphQL Projection
• gRPC Target
• Cohesive.CodeGen
• JavaScript And TypeScript Artifacts
• Integration With Other Cohesive Blocks
• The API Role In Cohesive

Why It Exists

Most API codebases duplicate the same facts in several places:

• server routes and handlers;
• OpenAPI documents;
• GraphQL schema views;
• generated clients;
• test mocks;
• frontend route constants;
• auth and tenant-scope rules;
• process and entity operation metadata.

Cohesive.Api makes those facts part of one source of truth. The API definition is not only documentation and not only routing. It is an IR that other Cohesive blocks can interpret.

API As IR

A Cohesive API definition contains endpoints and operations. Each operation carries:

• a stable operation id;
• an operation kind, such as query, command, or action;
• an optional entity binding;
• an HTTP projection, including method, route, parameters, body, and query DTOs;
• semantic result variants;
• optional transition metadata from Cohesive.Entities;
• optional scope policies from Cohesive.Identity;
• summaries, descriptions, and tags for generated documentation.

The API definition can then be emitted, served, projected, or bound without rebuilding the operation model.

ASP.NET Minimal API Binding

Cohesive.Api integrates directly with ASP.NET Minimal APIs. The Minimal API binding helpers map the declared route and HTTP method, then attach Cohesive metadata to the endpoint.

That metadata includes operation definitions, HTTP binding, result metadata, scope policies, and transition definitions. ASP.NET can use it for route handling, OpenAPI output, identity enrichment, process endpoints, and entity operation binding.

The binding remains conventional ASP.NET: handlers are still delegates, dependency injection still works, and route handlers can still be configured with ASP.NET policies. The difference is that the endpoint's semantic contract comes from the Cohesive API definition.

Identity And Scope Policies

Cohesive.Api is integrated with Cohesive.Identity through ApiScopePolicy.

An operation can declare how its identity scope is selected and checked: from a header, query parameter, route value, request body, ambient context, or resource-derived identifier.

The policy is attached to operations in the DSL.

var api = Cohesive.Api.Api.Define("Shipping")
    .Entity<Shipment>()
    .Query("Get")
        .Route("GET", "/api/shipments/{id}")
        .RouteParameter<Guid>("id")
        .Returns<ShipmentDto>()
        .Scope(ShippingTenantScope.SingleFromHeader())
        .Done()
    .Build();

The ASP.NET identity adapter reads endpoint scope-policy metadata, resolves the request identity context, validates selected scopes against grants, and attaches the normalized identity to OperationContext.

builder.Services.AddRequestIdentityContext(options =>
{
    options.ScopeKind = ShippingTenantScope.ScopeKind;
    options.SingleScopeHeaderName = "X-Tenant-Id";
    options.MultipleScopesHeaderName = "X-Tenant-Ids";
    options.ScopeModeHeaderName = "X-Tenant-Scope-Mode";
});

This keeps API authorization policy, transport parameter names, generated clients, and storage/process scope placement aligned.

OpenAPI Projection

The OpenAPI adapter emits OpenAPI 3.1 from an ApiDefinition. It emits paths, parameters, request bodies, response schemas, operation ids, summaries, tags, and Cohesive-specific extensions such as scope-policy metadata.

var emission = new OpenApiEmitter(new OpenApiEmitterOptions
{
    FileName = "shipping.openapi.generated.json",
    Title = "Shipping",
    Version = "2026.1",
    WriteIndented = true
}).Emit(new ApiCodeGenerationRequest(api));

The generated document can also be served from ASP.NET.

app.MapCohesiveOpenApi(
    definition: api,
    options: new()
    {
        Title = "Shipping",
        Version = "2026.1"
    },
    publishedDocumentName: "v1");

Because the document is emitted from the semantic definition, OpenAPI does not drift from server routing, scope metadata, or generated clients.

GraphQL Projection

Cohesive.Api can also emit a GraphQL schema view. Query operations are projected onto GraphQL query fields, command/action style operations can be projected onto mutation fields, and result variants can be represented through GraphQL types and unions.

var graphQl = new GraphQLSchemaEmitter(new GraphQLSchemaEmitterOptions
{
    SchemaName = "Shipping"
}).Emit(new ApiCodeGenerationRequest(api));

The ASP.NET GraphQL schema endpoint helper can serve both SDL and introspection JSON.

app.MapCohesiveGraphQLSchema(
    definition: api,
    options: new()
    {
        SchemaName = "Shipping"
    },
    publishedDocumentName: "v1"
    );

The GraphQL projection is a schema view over the same API IR. It does not require duplicating entity, request, response, or scope definitions.

gRPC Target

The API IR is structured so it can also be projected onto RPC-oriented transports such as gRPC.

For gRPC, the same semantic API data can map to service methods, request messages, response messages, and oneof response variants. This is especially useful for strongly typed internal service calls where the API definition should remain aligned with public HTTP/OpenAPI and GraphQL views.

The gRPC adapter is a target projection of the API model. Where an implementation binds it, it should preserve Cohesive semantics rather than flattening them into transport-only protobuf definitions.

Cohesive.CodeGen

Cohesive.Api code generation is built on Cohesive.CodeGen. API emitters implement IApiCodeEmitter and return CodeEmission documents.

public interface IApiCodeEmitter
{
    string Language { get; }

    CodeEmission Emit(in ApiCodeGenerationRequest request);
}

That makes API projections composable with other generated artifacts. A build can generate OpenAPI, GraphQL, TypeScript clients, Playwright mocks, shape declarations, presentation metadata, and contract constants from the same backend definitions.

JavaScript And TypeScript Artifacts

The TypeScript adapter emits rich frontend artifacts from ApiDefinition.

The generated client understands:

• operation names and endpoint ids;
• route parameters;
• query parameters and query DTOs;
• request bodies;
• typed response payloads;
• generated shape imports;
• scope-policy metadata;
• a shared HTTP client abstraction.

var clientEmission = new TypeScriptApiClientEmitter(new()
{
    FileName = "shipping.api.generated.ts",
    ShapesImportPath = "./shipping.shapes.generated",
    ModuleName = "Shipping"
}).Emit(new ApiCodeGenerationRequest(api));

The same API definition can emit typed Playwright route mocks for frontend tests.

var mockEmission = new TypeScriptPlaywrightApiMockEmitter(new()
{
    FileName = "shipping.api.mock.generated.ts",
    ModuleName = "Shipping"
}).Emit(new ApiCodeGenerationRequest(api));

This matters because frontend code should not hand-author endpoint strings, route parameter encoders, scope header names, or result builders when those facts are already known to the backend IR. Cohesive.CodeGen projects them into JavaScript and TypeScript artifacts so product UI code can call semantic API operations rather than assembling transport details manually.

Integration With Other Cohesive Blocks

Cohesive.Api is the API surface for the rest of the Cohesive stack.

Cohesive.Identity

API scope policies declare how identity scopes are selected and checked. ASP.NET adapters enforce those policies and attach normalized identity context to operations.

Cohesive.Storage

Entity and query APIs can be backed by semantic repositories. Scope metadata from the API can drive storage placement through identity-aware partition policies.

Cohesive.Entities

Command operations can attach transition definitions. ASP.NET entity adapters can bind API operations to entity loads, creates, queries, and transitions.

Cohesive.Processes

Process APIs can expose start, status, signal, and query operations. Process endpoint adapters bind API definitions to process runtimes while preserving identity and scope metadata.

Cohesive.Presentation

Generated API clients and scope metadata can be consumed by presentation projections so UI actions are tied back to declared backend operations.

The API Role In Cohesive

Cohesive.Api turns API design into a semantic artifact.

It provides:

• a C# DSL for declaring API operations;
• an immutable API IR;
• ASP.NET Minimal API binding;
• Cohesive.Identity scope-policy integration;
• OpenAPI emission and ASP.NET document endpoints;
• GraphQL schema and introspection emission;
• a path toward gRPC service projection;
• TypeScript API client generation;
• typed Playwright mock generation;
• Cohesive.CodeGen integration for multi-language artifacts;
• alignment with storage, entities, processes, and presentation.

The result is an API layer where product semantics are declared once and projected many times: served by ASP.NET, documented by OpenAPI, viewed through GraphQL, consumed by TypeScript, tested through generated mocks, and enforced through Cohesive.Identity.