GeezerVison is showing smithy.io — Smithy: Build services. Build SDKs.
Build services.
Build SDKs.
Build with Smithy.
Define your API once in a clear, protocol-agnostic language. Smithy generates type-safe clients, servers, and docs across ten languages from a single model, and it powers the APIs and SDKs at AWS.
- Open source, Apache 2.0
- Created and used at AWS
- 10+ languages
weather.smithy
$version: "2"namespace example.weather service Weather { version: "2006-03-01" resources: [City]} resource City { identifiers: { cityId: CityId } read: GetCity list: ListCities} @readonlyoperation GetCity { input := { @required cityId: CityId } output := { @required name: String }}
Write your API once. Generate everything.
One model in. SDKs, servers, docs, and OpenAPI out. smithy build does the rest.
Smithy model
weather.smithy
$
smithy build
-
Client SDKs
10 languages
-
Servers
TypeScript, Java
-
Documentation
API reference
-
OpenAPI
& JSON Schema
Client SDKs ship in ten languages
01
Protocol-agnostic by design
One model describes the shapes; the protocol decides the wire format. The same service serves REST JSON, RPC v2 CBOR, AWS JSON, and query/XML, so you can adopt new protocols without touching the model.
Explore protocols →
GET /cities/sea-01
content-type: application/json
{
"name": "Seattle",
"coordinates": {
"latitude": 47.6062,
"longitude": -122.3321
}
}
POST /service/Weather/operation/GetCity
smithy-protocol: rpc-v2-cbor
// CBOR is binary; shown decoded
{
name: "Seattle",
coordinates: { latitude: 47.6062, longitude: -122.3321 }
}
POST /
x-amz-target: Weather.GetCity
content-type: application/x-amz-json-1.0
{
"name": "Seattle",
"coordinates": { "latitude": 47.6062, "longitude": -122.3321 }
}
POST / · application/x-www-form-urlencoded
Action=GetCity&cityId=sea-01
<!-- XML response -->
<GetCityResult>
<name>Seattle</name>
<coordinates>
<latitude>47.6062</latitude>
</coordinates>
</GetCityResult>
02
Declarative API governance
Your standards live in the model, not in an external linter, so they are validated by smithy build itself and cannot be bypassed. Share the rules org-wide and catch design and quality issues before your customers do.
Read the guides →
zsh: smithy build
$smithy build
Validating model (142 shapes)…
✓RestJson1 protocol traits resolved
✓All operations have documentation
✓Pagination tokens type-checked
✕ ERRORMissingPaginatedTrait
ListCities returns a list but is not @paginated
at example.weather#ListCities (weather.smithy:24)
1 error, 0 warnings. Build failed.
03
Backward-compatible evolution
Extend the meta-model through traits to capture more about your services without breaking changes. Smithy checks every revision for backward compatibility.
Explore traits →
weather.smithy · diff
@error("client")
@retryable
structure ThrottlingError {
@required message: String
}
✓ Backward-compatible. No breaking change.
04
Resource-based modeling
Model your API as resources and operations. Smithy uses that structure to generate richer artifacts, from CloudFormation schemas to type-safe SDKs and docs.
Model resources →
model explorer
- service Weather
- resource City
- read · GetCity
- list · ListCities
- operation GetCurrentTime
“Smithy is the cornerstone of cross-team collaboration in our organization. The simplicity of the base language, rich extensibility, and the ease of writing correct tooling make it a must-try for organizations that want to evolve their APIs safely and efficiently.”
SiriusXM
Supported languages
Clients and servers, in your language.
One model compiles to idiomatic, type-safe code. No hand-written glue.
Build your first SDK in minutes.
Start with the quickstart, or read the full specification.
|
