AWS restJson1

aws.protocols#restJson1 is AWS’s REST/JSON protocol. NSmithy generates both a typed .NET client and an ASP.NET Core minimal API server adapter. Status: Preview.

Although the trait lives under aws.protocols, restJson1 is useful for non-AWS services too. It has broad Smithy ecosystem support and is the protocol to choose when you want OpenAPI generation through smithy-openapi.

See Protocol Status for current conformance numbers.

Maven Dependency

"software.amazon.smithy:smithy-aws-traits:1.71.0"

NuGet Packages

Purpose	Package
Client	NSmithy.Client
Server (ASP.NET Core)	NSmithy.Server.AspNetCore + Microsoft.AspNetCore.App

Modeling

Use @restJson1 on the service and Smithy’s standard HTTP binding traits on operations and members:

$version: "2"

namespace example.weather

use aws.protocols#restJson1

@restJson1
service Weather {
    version: "2026-01-01"
    operations: [GetCity]
}

@readonly
@http(method: "GET", uri: "/cities/{cityId}")
operation GetCity {
    input := {
        @required
        @httpLabel
        cityId: String
    }
    output := {
        @required
        name: String
    }
    errors: [NoSuchResource]
}

@error("client")
structure NoSuchResource {
    @required
    resourceType: String
}

Members without an explicit HTTP binding are serialized in the JSON body. restJson1 also carries AWS-specific behavior such as raw string/blob payloads, @requestCompression, @httpChecksumRequired, and AWS-style error deserialization.

On the Wire

GetCity binds cityId to the URI path label; the response comes back as a JSON body:

GET /cities/123 HTTP/1.1
Host: api.example.com
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{"name":"Seattle"}

Members without an HTTP binding are carried in the JSON body. Errors are discriminated by the X-Amzn-Errortype response header.

Usage

The generated IWeatherServiceHandler and WeatherClient are identical to every other HTTP-JSON/CBOR protocol — see Client & Server Usage for the handler and client code. Only the @restJson1 trait and the wire format above are specific to this protocol.

AWS notes

Explicit SigV4 signing exists in early preview; see Authentication. NSmithy does not yet provide AWS SDK-style endpoint resolution, credential chains, retries, or pagination helpers. Use the official AWS SDK for .NET for production calls to AWS services.