Postman tutorial for Viam's gRPC APIs

Postman tutorial for Viam's gRPC APIs

1. Overview

You can use the Viam web app to control your machines, or the Viam SDKs to develop frontend and backend applications. But if you want to explore what's happening behind the scenes, let's use Viam's gRPC API to control a rover.

Prerequisites

What You'll Learn

What You'll Need

What You'll Build

Watch the Video

Follow along with the step-by-step video.

Spin a rover with the Viam gRPC API

2. Fork the sample collection

In Postman, fork the following collection to your own workspace.

  1. Select the collection in the sidebar.
  2. Select the overflow menu ( ...), and Fork the collection.
  3. Enter a label for your fork, and select a workspace to save it to.
  4. Select Fork Collection.

Postman creates your fork in the selected workspace. You can now update this version of the collection as you wish. If you optionally chose to watch the collection, you can pull changes to your own collection when the main collection is updated.

3. Authorize API requests

Find your Viam credentials

  1. To find the API key and API key ID, go to the Viam app, select the machine you wish to connect to, and under the Connect tab, select a code sample language. Toggle Include API key, and then copy and paste the API key ID and API key to update your Postman variables
  2. To find the machine address, go to the Viam app, select the machine you wish to connect to, and under the Status dropdown, copy the Remote address to update your Postman variable.
  3. Input your credentials for api_key, api_key_id, and machine_url as Postman variables and Save your changes.

Authorization

To authorize subsequent calls to the Viam server running on your smart machine, generate access tokens in Postman.

  1. Invoke the AuthService / Authenticate method to generate an access token. Under the Messages tab, notice you are using your api_key and api_key_id to authorize the call to the app_url. Under the Scripts tab, notice code that saved the access token as a variable app_access_token for you to re-use in subsequent requests.
  2. Invoke the ExternalAuthService / AuthenticateTo method to generate an access token. Under the Scripts tab, notice code that saved the access token as a variable machine_access_token.
  3. For subsequent calls to Viam gRPC services, you can include the machine_access_token variable under the Authorization tab expressed with double curly braces like {{machine_access_token}} using the Bearer token authorization type in order to make calls to your machine_url.

4. Spin a Viam rover

Get resource names

  1. Invoke the RobotService / ResourceName method to get a list of resources associated with your machine. Notice you are using your machine_access_token to authorize the call to your machine_url.
  2. In the server response, find the base component, and make a note of the component's name. We will need it for the next step.

Spin a Viam rover

  1. Open the BaseService / Spin request. Once again, you are using your machine_access_token to authorize the call to your machine_url. This time, additional information is required. Under the Messages tab of your request, update the name property to the name of your own base component retrieved in the previous step.
  2. Invoke the method to spin your rover.

From here, you can continue updating the payload, exploring other hardware Components, software Services, and experiment with other cloud capabilities, such as machine learning.

5. Next Steps

This tutorial was a hands-on introduction to the Viam gRPC API. Browse other methods available using server reflection, or see some of them documented in the Viam gRPC API collection as a reference. Read more about how Viam uses gRPC and WebRTC for system architecture.

In most cases, you won't be developing applications or controlling them using the raw gRPC APIs. Instead, check out these resources:

Once you learn the fundamentals of working with your machine, you can start adding more intelligence and capabilities, such as the following.