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.
- A module is a collection of Protobuf files that are configured, built, and versioned as a logical unit. Modules are the basic unit of organization for all Buf operations.
- 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.
- A repository is the remote representation of a module within the BSR. Each generated SDK is created from the Protobuf code in a repository and the plugins you choose.
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:
Go to your dashboard and click Organizations in the left nav to see all of the organizations you belong to:
Click on an organization to view all of its repositories, then click on the repository you want to use.
Click the SDKs tab to see the generated SDKs for this repository:
For this tutorial, you can skip the above steps and go directly to the SDKs tab of the
eliza repository in the
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 branch or tag 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.
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:
- Run the configuration command, then either click the One-time registry configuration check box or click Completed.
- 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 branch or tag
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 branch or tag:
You can reset the module to latest by going back to the Current reference dropdown and choosing Reset current reference. To specify a specific plugin version to generate SDKs with, select the Plugin version dropdown for a given SDK under the Available SDKs section and choose a plugin version:
Notice that when you make these changes, the installation command updates to reflect the new version (this result is
from choosing the
$ npm install @firstname.lastname@example.org
This syntax identifies the plugin version first, and then the exact commit in the repository that the
represents. For more information on the specifics of the syntax, see the NPM guide.
The guides for the other dependency managers have similar sections.