Introduction to Smithy

1. Introduction

Smithy is a way to describe our APIs, along with a set of supporting tooling that enables us to generate API clients and servers from this definition. It allows us to describe our API and then generate client and server code from our definition.

In this tutorial, we’ll take a quick look at the Smithy IDL (Interface Definition Language) and its associated tooling.

2. What Is Smithy?

Smithy is an Interface Definition Language that allows us to describe our APIs in a language and protocol-agnostic format. Amazon originally designed Smithy for describing the AWS APIs, and they’ve since released it publicly so other services can benefit from the same tooling.

We can use the provided tooling to automatically generate server and client SDK code from these API definitions. This then allows us to have the Smithy files serve as the authoritative source of truth for how our API works, ensuring that all client and server code is correct in comparison to this.

Smithy is designed for defining resource-based APIs. The standard use for this is JSON over HTTP, but we can also use other serialisation formats such as XML, and even with non-HTTP transports, such as MQTT.

Smithy can be considered conceptually similar to other standards such as OpenAPI and RAML. However, Smithy takes a much more opinionated approach to how APIs should work – expecting them to be resource-based. At the same time, Smithy doesn’t prescribe how the transport or serialisation should work, allowing more flexibility there.

3. Smithy Files

We define our API by writing .smithy files in the Smithy IDL format. These files define our API in terms of resources, operations that we perform on the resources, and services that represent the entire API boundary.

Our Smithy files start by defining the version of the Smithy IDL format that we’re using and a namespace in which this API will exist:

$version: "2"
// The namespace to use
namespace com.baeldung.smithy.books

We then define our resources, operations, and services within this file, along with other necessary elements, such as the data structures required for operations.

3.1. Resources

The first thing we need to define is our resources. These represent the data we’ll be working with. These are defined using the resource keyword followed by the name of the resource. Within the resource, we define how to identify the resource and outline its associated properties. Later on, we’ll also add the operations that we can perform on the resource.

For example, we can define a resource representing a book:

/// Represents a book in the bookstore
resource Book {
    identifiers: { bookId: BookId }
    properties: {
        title: String
        author: String
        isbn: String
        publishedYear: Integer
    }
}

@pattern("^[a-zA-Z0-9-_]+$")
string BookId

Here, we have a Book resource. This is uniquely identified using the id field, of type BookId – which we’ve separately defined as being a String matching the given format. Our Book additionally has properties for title, author, isbn, and publishedYear. As such, here’s an example of this resource in the JSON format:

{
    "bookId": "abc123",
    "title": "Head First Java, 3rd Edition: A Brain-Friendly Guide",
    "author": "Kathy Sierra, Bert Bates, Trisha Gee",
    "isbn": "9781491910771",
    "publishedYear": 2022
}

3.2. Services

In addition to resources, our API also requires a service definition. These represent the actual server that’s working with our data. We can have as many of these as we need, each representing a different resource to manage.

We define our service with the service keyword followed by the name of the service. Within this, we then define the version of the service and the resources that it works with:

service BookManagementService {
    version: "1.0"
    resources: [
        Book
    ]
}

At this point, Smithy knows that we have a BookManagementService API that will manage Book resources, but not how to do that.

3.3. Lifecycle Operations

Once we have a resource, we need to be able to perform operations on it. Smithy supports a set of standard lifecycle operations that we can perform:

• create – Used to create a new instance of the resource, where the service generates the IDs
• put – Used to create a new instance of the resource, where the client provides the IDs
• read – Used to retrieve an existing instance of the resource by ID
• update – Used to update an existing instance of the resource by ID
• delete – Used to delete an existing instance of the resource by ID
• list – Used to list instances of the resource

Each operation is defined using the operation keyword and then the name of the operation. Within this, we define the expected input, output and error types.

For example, the operation to get a Book by ID might look like this:

/// Retrieves a specific book by ID
@readonly
operation GetBook {
    input: GetBookInput
    output: GetBookOutput
    errors: [
        BookNotFoundException
    ]
}

/// Input structure for getting a book
structure GetBookInput {
    @required
    bookId: BookId
}

/// Output structure for getting a book
structure GetBookOutput {
    @required
    bookId: BookId

    @required
    title: String

    @required
    author: String

    @required
    isbn: String

    publishedYear: Integer
}

/// Exception thrown when a book is not found
@error("client")
structure BookNotFoundException {
    @required
    message: String
}

The input to this is a single value – the bookId. On success, the output is then the details of our book. Alternatively, we might get an error if the book doesn’t exist.

Notably, although it may seem repetitive, the fields defined in the input and output structures for certain operations must match those in our resource appropriately. However, not all of them need to be included, as we can see from the GetBookInput structure that only has the bookId field.

We then need to indicate that this read operation applies to the Book resource:

resource Book {
    // ...
    read: GetBook
 }

At this point, Smithy now knows that this is an operation we can perform on our resource and how the inputs and outputs should work.

3.4. Non-Lifecycle Operations

Sometimes, we need to have operations that don’t relate to the lifecycle of our resources. For example, we might want an operation to recommend a book to read next.

We define these operations in the same way as lifecycle operations. However, when attaching them to our resource, we need to use the operations keyword instead:

resource Book {
    // ...
    operations: [
        RecommendBook
    ]
}

/// Recommend a book
@readonly
operation RecommendBook {
    input: RecommendBookInput
    output: RecommendBookOutput
}

/// Input structure for recommending a book
structure RecommendBookInput {
    @required
    bookId: BookId
}

/// Output structure for recommending a book
structure RecommendBookOutput {
    @required
    bookId: BookId

    @required
    title: String

    @required
    author: String
}

This then allows us to perform this new operation on our resources.

4. Code Generation

Now that we’ve written our Smithy file to describe our API, we need to be able to build the API itself. Fortunately, Smithy provides tools that automatically generate both client-side SDKs and server-side application services from our Smithy file.

In this article, we’re going to generate Java code. For this, there’s a Gradle plugin that we can use. Unfortunately, there’s no Maven equivalent at the moment, so if we’re going to use Smithy to generate code for our projects, we need to use Gradle as the build tool.

Both client and server code generation use the same Gradle plugin dependencies for smithy-jar and smithy-base, so we first need to ensure we add it to our settings.gradle file:

pluginManagement {
    plugins {
        id 'software.amazon.smithy.gradle.smithy-jar' version "1.3.0"
        id 'software.amazon.smithy.gradle.smithy-base' version "1.3.0"
    }
}

We also need to add the smithy-base plugin to our build.gradle file, as well as ensuring the java-library plugin is present:

plugins {
    id 'java-library'
    id 'software.amazon.smithy.gradle.smithy-base'
}

Next, we need to include the software.amazon.smithy.java.codegen:plugins dependency for the smithyBuild scope:

dependencies {
    smithyBuild "software.amazon.smithy.java.codegen:plugins:0.0.1"
}

Now we ensure that the smithyBuild task runs before the compileJava task:

tasks.named('compileJava') {
    dependsOn 'smithyBuild'
}

Finally, we need to write a smithy-build.json file for the plugin to use. For now, this needs the version of smithy-build – currently “1.0” – and the location of our Smithy files:

{
  "version": "1.0",
  "sources": [
      "./smithy/"
  ]
}

At this point, we’re ready to configure our build for client SDK and/or server code generation.

4.1. Configuring API Protocols

Before we can generate our code, we need to update our Smithy file to indicate the kind of API that we wish to generate. We’ll use the AWS restJson1 protocol.

To do this, we first need to tag our service definition to indicate this is the protocol to use:

@aws.protocols#restJson1
service BookManagementService {
    // ...
}

Next, we tag each operation to specify the HTTP method and URI it uses:

@readonly
@http(method: "GET", uri: "/books/{bookId}")
operation GetBook {
    // ...
}

Here, we’ve indicated that the GetBook operation is exposed using the GET method under the /books/{bookId} URI. The bookId path parameter is taken from the input structure. So, for example, a book with the ID abc123 will be accessed using GET /books/abc123.

4.2. Generating Client SDKs

To generate a client SDK, we need to configure the java-client-codegen plugin in our smithy-build.json file:

{
    ...
    "plugins": {
        "java-client-codegen": {
            "service": "com.baeldung.smithy.books#BookManagementService",
            "namespace": "com.baeldung.smithy.books.client",
            "protocol": "aws.protocols#restJson1"
        },
    }
}

This tells the build to generate code into the com.baeldung.smithy.books.client Java package, and to do so for the BookManagementService within the com.baeldung.smithy.books namespace from our Smithy files.

We also need to add the software.amazon.smithy.java:aws-client-restjson dependency to our build.gradle file to build a client SDK for the AWS restJson1 protocol:

dependencies {
    // ...
    implementation "software.amazon.smithy.java:aws-client-restjson:0.0.1"
}

This then causes the build to generate Java source files in an area under the build directory. To compile these, we then need to tell Gradle about them:

afterEvaluate {
    def clientPath = smithy.getPluginProjectionPath(smithy.sourceProjection.get(), "java-client-codegen")
    sourceSets.main.java.srcDir clientPath
}

Running our build now generates a set of Java classes that we can use to interact with the API. In particular, we’ll obtain both a synchronous and an asynchronous client, as well as DTOs to represent all of our inputs and outputs. These are then immediately ready to use to interact with the API:

BookManagementServiceClient client = BookManagementServiceClient.builder()
  .endpointResolver(EndpointResolver.staticEndpoint("http://localhost:8888"))
  .build();

GetBookOutput output = client.getBook(GetBookInput.builder().bookId("abc123").build());
assertEquals("Head First Java, 3rd Edition: A Brain-Friendly Guide", output.title());

Here we’re using the client to make a call to the service running on http://localhost:8888 and retrieving the title of the book with ID “abc123“.

4.3. Generating Server Stubs

We can generate server stubs in a very similar manner, using the java-server-codegen plugin instead:

{
    ...
    "plugins": {
        "java-server-codegen": {
            "service": "com.baeldung.smithy.books#BookManagementService",
            "namespace": "com.baeldung.smithy.books.server"
        },
    }
}

As before, this generates the code for the BookManagementService within the com.baeldung.smithy.books namespace from our Smithy files into the com.baeldung.smithy.books.server Java package.

We also need to add the software.amazon.smithy.java:aws-server-restjson dependency to our build.gradle file to build server stubs for the AWS restJson1 protocol and the software.amazon.smithy,java:server-netty dependency for the actual HTTP server:

dependencies {
    // ...
    implementation "software.amazon.smithy.java:server-netty:0.0.1"
    implementation "software.amazon.smithy.java:aws-server-restjson:0.0.1"
}

This then causes the build to generate Java source files into an area under the build directory. As before, to compile these, we then need to tell Gradle about them:

afterEvaluate {
    def serverPath = smithy.getPluginProjectionPath(smithy.sourceProjection.get(), "java-server-codegen")
    sourceSets.main.java.srcDir serverPath
}

Running our build now generates a set of Java classes that we can use as stubs for our server. However, this isn’t yet a working server. We also need to set up the server itself and provide implementations of our operations.

Our generated code provides interfaces for each of the operations in our service, as well as classes for the inputs and outputs of these operations:

/**
 * Retrieves a specific book by ID
 */
@SmithyGenerated
@FunctionalInterface
public interface GetBookOperation {
    GetBookOutput getBook(GetBookInput input, RequestContext context);
}

We need to write our own classes that implement each of these interfaces:

class GetBookOperationImpl implements GetBookOperation {
    public GetBookOutput getBook(GetBookInput input, RequestContext context) {
        return GetBookOutput.builder()
          .bookId(input.bookId())
          .title("Head First Java, 3rd Edition: A Brain-Friendly Guide")
          .author("Kathy Sierra, Bert Bates, Trisha Gee")
          .isbn("9781491910771")
          .publishedYear(2022)
          .build();
    }
}

Once we’ve done this, we can then create and start our HTTP server:

Server server = Server.builder()
  .endpoints(URI.create("http://localhost:8888"))
  .addService(
    BookManagementService.builder()
      .addCreateBookOperation(new CreateBookOperationImpl())
      .addGetBookOperation(new GetBookOperationImpl())
      .addListBooksOperation(new ListBooksOperationImpl())
      .addRecommendBookOperation(new RecommendBookOperationImpl())
      .build()
  )
  .build();

server.start();

At this point, we have a fully functional API implementing the specification defined in our Smithy file.

5. Conclusion

In this article, we’ve taken a brief look at Smithy and what we can do with it. We’ve seen how we can use the IDL language to describe our APIs, and then how we can generate both client-side SDKs and server-side stubs from this API definition. We can achieve a lot more using this framework, so the next time you need to create an API, it’s well worth a look.