Real-time data integration: gRPC implementation

This document outlines guidelines for implementing gRPC-based real-time data integrations. All new real-time data integrations should use gRPC. While HTTP-based integrations may exist for legacy use cases, all new feature development and enhancements are designed for gRPC.

These guidelines apply whether the service is:

Hosted by the partner
Deployed in the Index Cloud

gRPC integration build guide

Download the official OpenRTB 2.6 Protocol Buffers specification.
Get the necessary build and proto files.
To generate the language-specific OpenRTB and gRPC bindings required by your service, from the command line:
1. Install make and the latest version of protoc.
2. From the build files that you downloaded, open the Makefile and choose the language(s) for which the Protocol Buffers object code should be generated.
3. Run: make

Classification endpoint

Endpoint Description

Endpoint	Description
Partners must expose an endpoint accessible through a gRPC request following the agentic RTB Protobuf Schema that you downloaded with your build files.	The SLA for Index to use your response in our auction processing is 5 milliseconds. All requests should be made in approximately 5 milliseconds, with no more than 5% of requests allowed to exceed the timeout value specified in the `tmax` value. If more than 5% of requests time out, traffic to your container will be automatically throttled, and Index may lower the QPS accordingly. Calls to this endpoint will use keep-alive connections to minimize network overhead. Note: This specification will be continually updated to support new requirements. Let us know if you have new fields that you would like Index to support.

Partners must expose an endpoint accessible through a gRPC request following the agentic RTB Protobuf Schema that you downloaded with your build files.

The SLA for Index to use your response in our auction processing is 5 milliseconds. All requests should be made in approximately 5 milliseconds, with no more than 5% of requests allowed to exceed the timeout value specified in the tmax value. If more than 5% of requests time out, traffic to your container will be automatically throttled, and Index may lower the QPS accordingly. Calls to this endpoint will use keep-alive connections to minimize network overhead.

Note: This specification will be continually updated to support new requirements. Let us know if you have new fields that you would like Index to support.

Response codes

Standard gRPC status codes should be returned.

Circuit breaker logic

If Index receives any status code other than OK, or more than 5% of requests have exceeded an HTTP timeout value of 30 ms, Index's internal circuit breaker logic is triggered, and requests to the affected partner's API are throttled. Requests to a partner's API that time out will also trigger this same circuit breaker logic. Circuit breaker logic exists to protect both Index and our partners' systems. When errors rates return to nominal levels, circuit breakers will reopen and regular traffic volume will resume.

gRPC-supported lifecycle extension points and mutations