Smithy is an open source project by AWS with which you can model your APIs, generate code and documentation for clients and servers, as well as other artifacts, in many programming languages.

Smithy sprung out AWS's need of adopting a common format for its hundreds of APIs that would allow them to scale;most people associate scaling with handling server load but that also applies to APIs too. That is prevalent on AWS which supports SDKs in eleven programming languages and 270 services which get daily updated. That chaos had to be managed some way.

The solution to the problem was the introduction of Smithy, an IDL (Interface Definition Language) alike OpenAPI that describes services and comprises of libraries that can generate code and other artifacts, but code generation being the main motivator for using Smithy.

Smithy was initially developed for use in Amazon's own services and internal use but has been nevertheless released to the public as an open source project since 2019. As a matter of fact Smithy has now become the default choice at Amazon for modeling services.

Why is that? First of all it's a protocol-agnostic IDL, meaning that it is designed to work with any programming language, describe services running in any environment, and work with any kind of transport or serialization format. Then, its code generation can be extended with custom traits and enable automatic API standards enforcement.

Here is an example of a service defined with its Smithy's IDL own grammar and syntax:

$version: "2"
namespace example.weather

service Weather {
version: "2006-03-01"
resources: [City]
operations: [GetCurrentTime]
}

resource City {
identifiers: { cityId: CityId }
read: GetCity
list: ListCities
resources: [Forecast]
}

From there on and in order to generate code you need the Java smithy gradle plugin or the cli.
Smithy can generate code like this in multiple languages including typescript, go, rust, kotlin, swift and lately Python too.

The new Python code generator comes with the following features:

• Code is generated and type hinted – Code for clients, operations, and all the data they contain will be code generated into python classes. Along with type hints, this will allow customers to easily lint and debug their code using tools like mypy or other type analysis tooling.
• Interceptors – Interceptors are the new extensibility feature that replace the botocore event system. They’re designed to be more reliable and to be consistent across all of Smithy’s supported languages.
• Async first – Async is increasingly important in the Python ecosystem, and since clients spend much of their time blocked on IO they’re the perfect use case for it. All operations will therefore be generated as async functions.
• Configurable components – All of the core components of the client will be fully configurable. If you want to use tornado as the underlying http library, for example, you can easily do that.

To use the new generator there's two prerequisites. The first is Python of course of a minimum required version of 3. 11 and the second is Java 17, which is only required to build the generator.

That aside, Smithy can also be used for Linting and Validation to ensure APIs adhere to the best practices and standard. It can generate OpenAPI models too. Compared to OpenAPI, Smithy appears to be a kind of abstract high-level language for defining apis, while OpenAPI is more like assembly that Smithy can be compiled to.

On the project's road map there's releasing client code generators in every language supported by the aws sdks, a language server protocol implementation and the corresponding ide plugins for visual studio code and intellij.

So if you want to take advantage of Amazon's experience in building and managing hundreds of services and SDKs in your own APIs, give Smithy a go.

More Information

Smithy
Introducing Smithy for Python

Related Articles

Redocly CLI - The Super Tool For API Management

AWS Lambda Adopts Python 3.11

To be informed about new articles on I Programmer, sign up for our weekly newsletter, subscribe to the RSS feed and follow us on Twitter, Facebook or Linkedin.

Comments

Make a Comment or View Existing Comments Using Disqus

or email your comment to: comments@i-programmer.info