gRPC

Use Sift’s gRPC API with official client libraries or grpcurl.

Sift’s gRPC API handles high-frequency telemetry ingestion and real-time analysis. It uses Protocol Buffers to define services and messages for efficient, high-throughput communication. You can interact with it in multiple ways:

• Directly using standard tools like grpcurl or by writing your own gRPC clients.
• Using Sift’s pre-built client libraries, available for select programming languages to simplify setup.

Client libraries use gRPC interceptors to automate authentication and request handling. To authenticate a request directly, see Authenticate with the API.

Listing services from the command line

You can use grpcurl to explore Sift’s available gRPC services directly from the command line.

List all available services

  grpcurl $SIFT_GRPC_BASE_URL:$PORT_NUM list

List all endpoints of a particular service

grpcurl $SIFT_GRPC_BASE_URL:$PORT_NUM list sift.assets.v1.AssetService

gRPC base URL and port: Do not include https:// in the base URL, use only the hostname. $PORT_NUM is always 443.

Official client libraries

Sift provides pre-built client libraries for Python, Rust, and Go, maintained as open source in the Sift GitHub repository. These libraries use the gRPC API internally. Supported languages:

• Python
• Rust
• Go

Other languages

If your preferred language doesn’t yet have a dedicated client library, you can instead:

• Generate a client with Buf to compile Sift’s Protocol Buffers into gRPC client code for your preferred language.
• Use the Sift REST API, a standard HTTP-based interface for integration.

URL formatting for official gRPC clients

The required format for official gRPC API URLs depends on your client library. Some libraries require you to omit the URL scheme and port number, while others expect them to be included. Refer to the documentation of your chosen client library to confirm the expected URL format.

Port: The gRPC API uses port 443 by default in all environments.

Connect with an official client

Python

1. Create a Python environment.

     python3 -m venv venv 
   

2. In your Python environment (venv) install the Sift Python package:

   pip install sift-stack-py
   

3. In your Python environment directory, create a file named main.py and paste the following code:

   import os
   
   from sift.ping.v1.ping_pb2 import PingRequest
   from sift.ping.v1.ping_pb2_grpc import PingServiceStub
   from sift_py.grpc.transport import SiftChannelConfig, use_sift_channel
   
   if __name__ == "__main__":
       apikey = os.getenv("SIFT_API_KEY")
       assert apikey
   
       uri = os.getenv("SIFT_GRPC_BASE_URL")
       assert uri
   
       channel_config: SiftChannelConfig = {
           "apikey": apikey,
           "uri": uri,
       }
   
       with use_sift_channel(channel_config) as channel:
           response = PingServiceStub(channel).Ping(PingRequest())
           print(response)
   

4. In your Python environment directory, run the following command after replacing the placeholders ($SIFT_API_KEY and $SIFT_GRPC_BASE_URL) with your actual values:

   SIFT_GRPC_BASE_URL=$SIFT_GRPC_BASE_URL:$PORT_NUM SIFT_API_KEY=$SIFT_API_KEY python main.py
   

See the Python client documentation for the full API reference.

Rust

1. Create a Rust project.

   cargo new my_sift_project
   

2. In your Rust project, add the sift_rs crate.

   cd my_sift_project
   cargo add sift_rs
   

3. In your Rust project, add the tokio runtime.

   cargo add tokio --features full
   

4. Copy and paste the following into your my_sift_project/src/main.rs:

   use sift_rs::{
       Credentials, SiftChannelBuilder,
       ping::v1::{PingRequest, ping_service_client::PingServiceClient},
   };
   use std::env;
   
   #[tokio::main]
   async fn main() {
       let credentials = Credentials::Config {
           apikey: env::var("SIFT_API_KEY").unwrap(),
           uri: env::var("SIFT_GRPC_BASE_URL").unwrap(),
       };
   
       let conn = SiftChannelBuilder::new(credentials).build().unwrap();
       let mut ping_service = PingServiceClient::new(conn);
       let ping_response = ping_service.ping(PingRequest::default()).await.unwrap();
   
       println!("{}", ping_response.into_inner().response);
   }
   

5. In your Rust project directory, run the following command after replacing the placeholders ($SIFT_API_KEY and $SIFT_GRPC_BASE_URL) with your actual values:

   SIFT_GRPC_BASE_URL=$SIFT_GRPC_BASE_URL:$PORT_NUM SIFT_API_KEY=$SIFT_API_KEY cargo run
   

Go

1. Set up a dedicated directory and initialize it as a Go module using go mod:

   mkdir go-client-connection && cd go-client-connection
   go mod init sift_go_project
   

2. Use go get to fetch the Sift Go SDK and include it in your project:

   go get github.com/sift-stack/sift/go
   

3. In the sift_go_project directory, create a main.go file and copy and paste the following into that file:

   package main
   
   import (
       "context"
       "fmt"
       "log"
       "os"
   
       "github.com/sift-stack/sift/go/gen/sift/ping/v1"
       "github.com/sift-stack/sift/go/grpc"
   )
   
   func main() {
       ctx := context.Background()
       channelConfig := grpc.SiftChannelConfig{
           Uri:    os.Getenv("SIFT_GRPC_BASE_URL"),
           Apikey: os.Getenv("SIFT_API_KEY"),
       }
       conn, err := grpc.UseSiftChannel(ctx, channelConfig)
       if err != nil {
           log.Fatalln(err)
       }
       pingClient := pingv1.NewPingServiceClient(conn)
       res, err := pingClient.Ping(ctx, &pingv1.PingRequest{})
       if err != nil {
           log.Fatalln(err)
       }
       fmt.Println(res.Response)
   }
   

4. Verify and tidy up your module dependencies:

   go mod tidy 
   

5. In your Go module, run the following command after replacing the placeholders ($SIFT_API_KEY, $SIFT_GRPC_BASE_URL, and $PORT_NUM) with your actual values:

   SIFT_GRPC_BASE_URL=$SIFT_GRPC_BASE_URL:$PORT_NUM SIFT_API_KEY=$SIFT_API_KEY go run .