gRPC (Protocol Buffers)
Overivew
Sift's gRPC API is designed for high-frequency telemetry ingestion and real-time analysis, offering optimized performance and scalability. It uses Protocol Buffers for defining services and messages, enabling efficient, high-throughput communication. You can interact with Sift's gRPC API 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.
- Sift's client libraries internally use the gRPC API. If a client library is not available for your preferred language, you can manually generate client code from Sift's Protocol Buffers or use command-line tools to interact with the gRPC API.
- To learn how to authenticate with the gRPC API, see Authenticate with the gRPC API.
- Client libraries use gRPC interceptors to automate authentication and request handling.
Listing services from the command line
You can use grpcurl
to explore Sift's available gRPC services directly from the command line.
- Replace
$SIFT_GRPC_BASE_URL
and$PORT_NUM
with your actual gRPC endpoint and port. - When running a
grpcurl
command, do not includehttps://
in the base URL. The base URL should consist only of the hostname without any protocol prefix. - The
$PORT_NUM
placeholder should be replaced with443
, which is the required port for the gRPC base URL in all environments.
Official client libraries to connect with Sift's gRPC API
Sift provides pre-built client libraries for select programming languages, designed to simplify and accelerate integration with Sift's gRPC API. Sift's official client libraries internally use the gRPC API. These libraries offer helpful utilities and reduce the boilerplate required to get started. All libraries are open source and maintained in the Sift GitHub repository. Supported languages:
Language | Library | Quickstart | Documentation |
---|---|---|---|
Python | sift-stack-py | Example | Python documentation |
Rust | sift_rs | Example | Rust documentation |
Go | github.com/sift-stack/sift/go | Example | Go documentation |
Using other languages to connect with Sift's gRPC API
If your preferred language doesn't yet have a dedicated client library, you can instead:
- Compile Sift's Protocol Buffers manually to generate gRPC client code in your preferred language.
- Use the Sift REST API, which provides 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.
Language | Requires https:// prefix | Requires port number |
---|---|---|
Python | No | No |
Rust | Yes | No |
Go | No | Yes |
The gRPC API uses port 443
by default in all environments.
Quickstart: Connect to the gRPC API with an official Sift client
Python
To quickly connect with Sift's Python client, consider the following steps:
-
Create a Python environment.
-
In your Python environment (
venv
) install the Sift Python package: -
In your Python environment directory, create a file named
main.py
and paste the following code: -
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_API_KEY
: To learn how to create an API key, see Create an API key.$SIFT_GRPC_BASE_URL
:- The Python client allows you to omit the URL scheme and port number.
- To learn how to obtain the base URL for gRPC requests, see Obtain the base URL for REST/gRPC requests.
Rust
To quickly connect with Sift's Rust client, consider the following steps:
-
Create a Rust project.
-
In your Rust project, add the
sift_rs
crate. -
In your Rust project, add the
tokio
runtime. -
Copy and paste the following into your
my_sift_project/src/main.rs
: -
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_API_KEY
: To learn how to create an API key, see Create an API key.$SIFT_GRPC_BASE_URL
:- The Rust client requires you to add the URL scheme while adding the port number is optional.
- To learn how to obtain the base URL for gRPC requests, see Obtain the base URL for REST/gRPC requests.
Go
To quickly connect with Sift's Go client, consider the following steps:
-
Set up a dedicated directory and initialize it as a Go module using
go mod
: -
Use
go get
to fetch the Sift Go SDK and include it in your project: -
In the
sift_go_project
directory, create amain.go
file and copy and paste the following into that file: -
Verify and tidy up your module dependencies:
-
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
: The base URL for Sift gRPC requests.- The Go client expects the base URL without the URL scheme (for example, use
api.siftstack.com
, nothttps://api.siftstack.com
). - To learn how to obtain the base URL for gRPC requests, see Obtain the base URL for REST/gRPC requests.
- The Go client expects the base URL without the URL scheme (for example, use
$PORT_NUM
: The port number used for gRPC connections.- Defaults to
443
in all environments. - The Go client requires you to explicitly include the port number.
- Defaults to
$SIFT_API_KEY
: Your Sift API key for authentication.- To learn how to generate an API key, see Create an API key.