NSmithy

Define your contract

Start by describing your API in Smithy IDL — operations, input and output shapes, and traits. Smithy is protocol-agnostic: the same model can drive a REST service, a gRPC service, or both at once.

$version: "2"
namespace example.hello

use aws.protocols#restJson1

/// A simple greeting service.
@restJson1
service HelloService {
    version: "2024-01-01"
    operations: [SayHello]
}

/// Returns a greeting for the given name.
@readonly
@http(method: "GET", uri: "/hello/{name}")
operation SayHello {
    input := {
        /// The name to include in the greeting.
        @required
        @httpLabel
        name: String
    }
    output := {
        /// The greeting message, e.g. `"Hello, World!"`.
        @required
        message: String
    }
}

Implement server stubs

NSmithy generates a typed handler interface — one method per service operation. You fill in the business logic; routing, serialization, and protocol binding are handled by the generated ASP.NET Core adapter.

using Example.Hello; // generated by NSmithy

public class HelloHandler : IHelloServiceHandler
{
    public Task<SayHelloOutput> SayHelloAsync(
        SayHelloInput input,
        CancellationToken ct = default
    )
    {
        return Task.FromResult(new SayHelloOutput("Hello, " + input.Name + "!"));
    }
}

builder.Services.AddHelloServiceHandler<HelloHandler>();
app.MapHelloServiceHttp();

Use the generated client

NSmithy generates a typed async client with one method per operation. Inputs and outputs are strongly-typed C# records — no string URLs, no manual JSON, no reflection.

using Example.Hello; // generated by NSmithy

IHelloServiceClient client = new HelloServiceClient(transport, options);

var response = await client.SayHelloAsync(new SayHelloInput("World"));
Console.WriteLine(response.Message); // Hello, World!

Document your APIs

NSmithy generates an interactive Scalar OpenAPI explorer and Sphinx reference documentation straight from the Smithy model — no manual spec authoring. Both are built at compile time and served as static files by ASP.NET Core.

app.MapSmithyOpenApi(); // Scalar UI   →  /openapi
app.MapSmithyDocs();    // Smithy Docs →  /docs

Cross-ecosystem

Smithy is the IDL behind AWS’s public APIs. The same contract generates clients in Java, Python, TypeScript, Rust, Swift, and more.

Protocol agnostic

Smithy is protocol agnostic. NSmithy can generate servers and clients for multiple API protocols — REST, JSON-RPC, gRPC, CBOR — and more through extensibility.

MSBuild integration

No separate codegen step. MSBuild invokes smithy build, adds generated .g.cs files to compilation, and tracks model changes for incremental builds.

Type-safe contracts

Generated handler interfaces and client methods are strongly typed. No string URLs, no manual serialization, no runtime surprises.