Protocols
NSmithy binds modeled operations to the protocols below. For the separation between a contract and its wire representation, see Protocol bindings.
Choose a protocol
Section titled “Choose a protocol”| Protocol | Generated APIs | Choose it for |
|---|---|---|
restJson1 | Client and server | General REST APIs, broad tooling support, streaming, and AWS-compatible behavior |
simpleRestJson | Client and server | Alloy and Smithy4s interoperability |
rpcv2Cbor | Client and server | Compact binary RPC with CBOR and event streaming |
rpcv2Json | Client and server | Smithy RPC with JSON bodies and event streaming |
grpc | Client and server | Standard gRPC and protobuf interoperability |
awsJson1_1 | Client | Existing AWS JSON RPC services |
awsJson1_0 | Client | Existing AWS JSON 1.0 services |
awsQuery | Client | Existing AWS Query services |
ec2Query | Client | Existing EC2 Query services |
restXml | Client | Existing AWS XML services such as S3 |
For most new HTTP APIs, start with restJson1. Use rpcv2Cbor for compact
binary Smithy RPC between compatible peers, or rpcv2Json for the same RPC
model with readable JSON bodies. Use gRPC when standard protobuf and
gRPC interoperability matter. The AWS Query, AWS JSON, and restXml protocols
are primarily for existing AWS services and emulators.
See Protocol Status for maturity and current conformance numbers.
Services with multiple protocols
Section titled “Services with multiple protocols”A service can declare more than one supported protocol. Generated clients can select a non-default protocol through their configuration, and generated servers can map several protocols to the same handler.
See Hosting and Multiple Protocols for route mapping and Client Configuration for protocol selection.
Other protocols
Section titled “Other protocols”A protocol that is not listed here can be added from a separate package, without changes to NSmithy. Generated clients and servers then use it like a built-in one. See Extending NSmithy.