Define a New Resource API

You can define a new, custom resource API if:

• You have a resource that does not fit into any of the existing component or service APIs.
• You have a resource that could fit into an existing API, but you want to define an API with different methods and messages than the one in the existing APIs.

Define your new resource API

Viam uses protocol buffers for API definition.

To define a new API, you need to define the methods and messages of the API in protobuf, write code in Python or Go to implement the higher level server and client functions required, and generate all necessary protobuf module files. The following steps guide you through this process in more detail:

1. Decide whether your custom API is a component or a service. If it provides an interface to control hardware, it is a component. If it provides higher-level functionality, it is a service.

2. Choose a name for your API. This is called the subtype of your API. For example, gizmo.

   Determine a valid API namespace triplet based on your API name. You can figure out the model namespace triplet later when you create a model that implements your custom API.

   API namespace triplet and model namespace triplet example

   The viam-labs:audioout:pygame model uses the module name audioout. It implements the custom API viam-labs:service:audioout:

   {
     "api": "viam-labs:service:audioout",
     "model": "viam-labs:audioout:pygame"
   }
   

   For your custom API, your API namespace triplet might be your-org-namespace:component:gizmo where your-org-namespace is your organization namespace, found in your org settings page in the Viam app.

3. Create a directory for your module. Within that, create a directory called src.

   Tip

   If you are writing your module using Python, you can use this module generator tool to generate stub files for the new API as well as a new module that implements the new API.

4. Define your new API:

   • Write the proto methods in a <API name>.proto file inside your src/proto directory. For reference:
     • Example modular component proto file
     • Example modular service proto file
     • Built-in Viam resource proto files
   • And define the proto methods in a protobuf-supported language such as Python or Go in a file called api.py or api.go, respectively.
     • Example component in Python
     • Example service in Python

5. In the root directory of your module, you need to generate some configuration files. You will typically need the following three files for most modules, though different files are required for some advanced use cases. See the Buf documentation for instructions.

   • buf.yaml
   • buf.gen.yaml
   • buf.lock

6. In the /src/ directory of your module, use the protobuf compiler to generate all other necessary protocol buffer code, based on the <API name>.proto file you wrote.

   • Example generated files for a Python-based service. The buf. files were generated. The speech.proto was manually written.

Next steps