Buf Schema Registry (BSR)

Using generated SDKs – Tutorial

Generated SDKs are created by the Buf Schema Registry (BSR) and contain code generated from Protobuf schemas and plugins. They can be installed as dependencies using popular package managers like NPM, Go, Maven/Gradle, and Swift Package Manager, enabling you to easily consume Protobuf APIs without manually generating code or interacting with the schemas directly. For example, mobile or web teams that do not directly own Protobuf schemas can use generated SDKs to consume Protobuf APIs from other teams.

Prerequisites

Key concepts

module
A module is the key primitive in the Buf ecosystem, and represents a collection of Protobuf files that are configured, built, and versioned as a logical unit.
workspace
Workspaces are collections of modules that are defined together in the same buf.yaml file to create a local working environment. All modules in a workspace can import each other without specific dependency declarations, and can also share any dependencies that are defined for the workspace. Workspaces are the default input for Buf CLI commands.
plugins
Plugins are external programs that enable the transformation of Protobuf schemas into other constructs. They're used in this context to generate the client code that is packaged into the generated SDKs.
repository
A Buf Schema Registry (BSR) repository is a remote location representing a module's commits, labels, and label histories. Repositories are the basis of all of the BSR's features and shareable artifacts.

1. Find generated SDKs

Usually, you'll have a direct URL for the repository you want to use, either from the API owner or from your internal documentation. You can also search for a repository if you know its name, or browse what's available to you:

  1. Go to your dashboard, click on your username, and click Organizations to see all of the organizations you belong to:

    Screen shot of user dropdown
  2. Click on an organization to view all of its repositories, then click on the repository you want to use.

  3. Click the SDKs tab to see the generated SDKs for this repository:

    Screen shot of top nav with SDKs tab selected

For this tutorial, you can skip the above steps and go directly to the SDKs tab of the eliza repository in the connectrpc organization.

2. Choose language, plugins, and package manager

You have control over what's included in your SDK—you can choose the repository (which you've already done) and then choose the language, plugins, package manager, and the label of the repository itself. This enables you to key development to a specific version of the schema. Once you choose the language, the BSR will default to that language in the future unless you change it.

You can include multiple plugins by clicking on more than one to select them, but for this tutorial, you'll just use one.

  1. Once you're in the module's SDKs tab, the BSR presents a language picker. Click JavaScript.

    Screen shot of language picker
  2. A gallery of JavaScript-compatible plugins appears. Click connectrpc/es to choose the connectrpc_es plugin.

    Screen shot of plugin picker
  3. Click Continue. A panel with the available package managers and installation instructions appears. You can choose a different manager than the default, but we'll stick with NPM.

3. Setup and installation

The Package Manager section allows you to choose between different managers, and provides a one-time configuration. The Available SDKs panel beneath it provides the installation instructions for the SDKs generated from the repository and each plugin you selected:

Screen shot of package manager panel
  1. Run the configuration command, then either click the One-time registry configuration check box or click Completed.
  2. Follow the provided installation instructions to install the SDK. You can now use the SDK, and can see a link to integration instructions.

4. Changing the label

The BSR defaults to providing SDKs at the latest module and plugin version unless otherwise specified. To pin SDKs to a specific repository version, select the Current reference dropdown near the top of the SDKs tab and choose a commit or label:

Screen shot of package manager panel

Notice that when you make these changes, the installation command updates to reflect the new version (this result is from choosing the demo label):

$ npm install @buf/connectrpc_eliza.connectrpc_es@1.0.0-20230913231627-233fca715f49.1

This syntax identifies the plugin version first, and then the exact commit in the repository that the demo label represents. For more information on the specifics of the syntax, see the NPM guide. The guides for the other dependency managers have similar sections.